NDIS_PD_POST_AND_DRAIN_BUFFER_LIST Rückruffunktion (ndis.h)

Artikel
02/29/2024

Die PacketDirect-Plattform (PD) ruft die PDPostAndDrainBufferList-Funktion eines PD-fähigen Miniporttreibers auf, um PD_BUFFER Strukturen in PD-Übertragungs-/Empfangswarteschlangen zu posten und alle zuvor bereitgestellten PD_BUFFER-Strukturen zu leeren, die abgeschlossen wurden.

Hinweis Sie müssen die Funktion mit dem typ NDIS_PD_POST_AND_DRAIN_BUFFER_LIST deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST NdisPdPostAndDrainBufferList;

VOID() NdisPdPostAndDrainBufferList(
  [in, out] NDIS_PD_QUEUE *Queue,
  [in, out] PD_BUFFER **PostBufferListHead,
  [in, out] PD_BUFFER ***DrainBufferListTail,
  [in]      ULONG MaxDrainCount
)
{...}

Parameter

[in, out] Queue

Ein Zeiger auf die Übertragungs- oder Empfangswarteschlange, die bereitgestellte Puffer empfängt und abgeschlossene Puffer entfernt hat.

[in, out] PostBufferListHead

Der Kopf der Beitragsliste. Der Anbieter entfernt die Puffer in dieser Liste und fügt sie der Warteschlange hinzu.

[in, out] DrainBufferListTail

Das Ende der Abflussliste. Der Anbieter entfernt alle abgeschlossenen Puffer aus der Warteschlange und fügt sie dieser Liste hinzu.

[in] MaxDrainCount

Die maximale Menge an PD_BUFFER Strukturen, die geleert werden sollen. Der Anbieter muss sicherstellen, dass dieser Betrag nicht überschritten wird. Ein Satz partieller PD_BUFFER Strukturen, aus denen eine einzelne L2-Paketanzahl besteht, ist 1.

Rückgabewert

Diese Rückruffunktion gibt keinen Wert zurück.

Hinweise

Der Anbieter entfernt Puffer aus der PostBufferList und platziert sie in der Warteschlange, beginnend mit dem Hauptpuffer in der Liste und dem Nächsten Puffer, bis entweder postBufferList leer oder die Warteschlange voll (oder fast voll) ist. Der Anbieter ist zum PostListHead-Element vorgerückt und gibt den neuen Listenkopf an den Aufrufer zurück. Der Anbieter entfernt auch alle abgeschlossenen Puffer aus der Warteschlange und fügt sie in das Ende der DrainBufferList ein und gibt das neue DrainBufferList-Tail an den Client zurück.

Hinweis Der Anbieter sollte so viele Puffer wie möglich leeren, um Platz für die bereitgestellten Puffer zu öffnen. PostBufferList und DrainBufferList sind garantiert nicht zusammenhängende Pufferlisten (der Client stellt niemals den Kopf einer Pufferliste als PostBufferListHead und das Ende derselben Liste wie DrainBufferListTail bereit).

Der Client kann auch eine leere Nachpufferliste übergeben, um einfach abgeschlossene Puffer zu leeren, ohne neue Puffer zu posten. Der Client kann maxDrainCount auch auf 0 festlegen, um nur neue Puffer zu veröffentlichen, ohne abgeschlossene Puffer zu leeren. In seltenen Fällen kann der Client den Aufruf sowohl mit einer leeren Postpufferliste als auch mit maxDrainCount auf 0 aufrufen. Der Anbieter darf nicht von einer anderen Annahme ausgehen und einen solchen Aufruf ordnungsgemäß verarbeiten, z. B. einen "No-Operation".

Beispiele

Um eine PDPostAndDrainBufferList-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der zu definierenden Funktion identifiziert. Windows bietet eine Reihe von Funktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Funktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine PDPostAndDrainBufferList-Funktion mit dem Namen "MyPDPostAndDrainBufferList" zu definieren, verwenden Sie den typ NDIS_PD_POST_AND_DRAIN_BUFFER_LIST , wie in diesem Codebeispiel gezeigt:

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST MyPDPostAndDrainBufferList;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
VOID
 MyPDPostAndDrainBufferList(
    NDIS_PD_QUEUE*  Queue,
    PD_BUFFER**  PostBufferListHead,
    PD_BUFFER*** DrainBufferListTail,
    ULONG  MaxDrainCount
    )
  {...}

Der NDIS_PD_POST_AND_DRAIN_BUFFER_LIST Funktionstyp ist in der Headerdatei Ntddndis.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, müssen Sie der Funktionsdefinition die anmerkung Use_decl_annotations hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den NDIS_PD_POST_AND_DRAIN_BUFFER_LIST Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für NDIS-Treiber.

Informationen zu Use_decl_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.

Im Folgenden finden Sie einen Beispielcodeausschnitt, der die Zeigerreferenzierungen für diese Funktion veranschaulicht.

PD_BUFFER* PostHead = NULL;
PD_BUFFER** PostTail = &PostHead;
PD_BUFFER* DrainHead = NULL;
PD_BUFFER** DrainTail = &DrainHead;

PD_BUFFER* bufX = <allocated PD_BUFFER>;

bufX->NextPDBuffer = NULL;
*PostTail = bufX;
PostTail = &bufX->NextPDBuffer;

// BEFORE:
//PostHead == bufX
//PostTail == &bufZ->NextPDBuffer
//DrainHead == NULL
//DrainTail == &DrainHead

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST(
          Queue,
          &PostHead,
          &DrainTail,
          32);

// AFTER:
//PostHead == bufY
//PostTail == &bufZ->NextPDBuffer
//DrainHead == buf1
//DrainTail == &buf5->NextPDBuffer

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 10
Unterstützte Mindestversion (Server)	Windows Server 2016
Zielplattform	Windows
Kopfzeile	ndis.h
IRQL	<= DISPATCH_LEVEL

Freigeben über