MINIPORT_PAUSE Rückruffunktion (ndis.h)

Artikel
08/07/2023

NDIS ruft die MiniportPause-Funktion eines Miniporttreibers auf, um den Fluss von Netzwerkdaten über einen angegebenen Miniportadapter zu beenden.

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

Syntax

MINIPORT_PAUSE MiniportPause;

NDIS_STATUS MiniportPause(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] PNDIS_MINIPORT_PAUSE_PARAMETERS PauseParameters
)
{...}

Parameter

[in] MiniportAdapterContext

Ein Handle für einen Kontextbereich, den der Miniporttreiber in seiner MiniportInitializeEx-Funktion zugeordnet hat. Der Miniporttreiber verwendet diesen Kontextbereich, um Zustandsinformationen für einen Miniportadapter zu verwalten.

[in] PauseParameters

Ein Zeiger auf eine NDIS_MINIPORT_PAUSE_PARAMETERS Struktur, die die Pausenparameter für den Miniportadapter definiert.

Rückgabewert

MiniportPause gibt einen der folgenden status Werte zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	MiniportPause hat den Fluss von Netzwerkdaten über den Miniportadapter erfolgreich beendet.
NDIS_STATUS_PENDING	MiniportPause hat den Pausenvorgang nicht abgeschlossen, und der Vorgang wird asynchron abgeschlossen. Der Miniporttreiber muss die NdisMPauseComplete-Funktion aufrufen, wenn der Vorgang abgeschlossen ist.

Hinweise

Ein Treiber gibt den MiniportPause-Einstiegspunkt an, wenn er die NdisMRegisterMiniportDriver-Funktion .

NDIS hält einen Miniportadapter an, um den Datenfluss zu beenden, der PnP-Vorgänge wie das Hinzufügen oder Entfernen eines Filtertreibers oder das Binden oder Aufheben der Bindung eines Protokolltreibers beeinträchtigen könnte.

NDIS ruft die MiniportPause-Funktion eines Miniporttreibers auf, um eine Pausenanforderung für den unter MiniportAdapterContext angegebenen Miniportadapter zu initiieren. Der Miniportadapter verbleibt im Zustand "Anhalten" , bis der Pausenvorgang abgeschlossen ist.

Für einen Miniportadapter im Zustand "Angehalten " ist der Miniporttreiber:

Wartet auf alle Aufrufe von Zurückzugebende NdisMIndicateReceiveNetBufferLists-Funktion .
Wartet darauf, dass NDIS den Besitz aller NET_BUFFER_LIST Strukturen aus ausstehenden Empfangsanzeigen an den Miniporttreiber zurückgibt. MiniportReturnNetBufferLists-Funktion .
Schließt alle ausstehenden Sendeanforderungen ab und ruft die NdisMSendNetBufferListsComplete-Funktion für alle ausstehenden Sendeanforderungen.
Lehnt alle neuen Sendeanforderungen ab, die an seine gesendet wurden. MiniportSendNetBufferLists-Funktion sofort durch Aufrufen von NdisMSendNetBufferListsComplete. Es sollte die vollständige status in jedem NET_BUFFER_LIST auf NDIS_STATUS_PAUSED festgelegt werden.
Kann status Hinweise mit dem NdisMIndicateStatusEx-Funktion .
Sollte OID-Anforderungen in der MiniportOidRequest-Funktion verarbeiten.
Sollte den Miniportadapter nicht vollständig beenden, wenn das Beenden des Miniportadapters verhindert, dass der Treiber Anforderungen verarbeitet oder status Hinweise bereitstellt.
Die Ressourcen, die der Treiber während der Initialisierung zugewiesen hat, sollten nicht freigegeben werden.

NDIS initiiert keine anderen PnP-Vorgänge für den Miniportadapter, z. B. Anhalten, Initialisieren, Stromwechsel, Anhalten oder Neustartanforderungen, während sich der Miniportadapter im Angehalten-Zustand befindet. NDIS kann diese PnP-Vorgänge initiieren, nachdem sich ein Miniportadapter im Zustand Angehalten befindet.

Nachdem ein Miniporttreiber alle ausstehenden Sendeanforderungen abgeschlossen hat und NDIS alle empfangenen Netzwerkdatenstrukturen (von ausstehenden Empfangsanzeigen) zurückgibt, muss der Treiber den Pausenvorgang abschließen. Wenn der Treiber NDIS_STATUS_SUCCESS aus MiniportPause zurückgibt, ist der Pausenvorgang abgeschlossen. Wenn der Treiber NDIS_STATUS_PENDING zurückgibt, kann der Miniportadapter im Anhalten-Zustand verbleiben, und der Angehalten-Vorgang ist abgeschlossen, nachdem der Treiber die NdisMPauseComplete-Funktion aufgerufen hat . Nach Abschluss des Pausenvorgangs befindet sich der Miniportadapter im Zustand Angehalten .

Für einen Miniportadapter im Zustand Angehalten :

Muss alle Sendeanforderungen an MiniportSendNetBufferLists sofort ablehnen, indem NdisMSendNetBufferListsComplete aufgerufen wird. Es sollte das Status-Element in jedem NET_BUFFER_LIST auf NDIS_STATUS_PAUSED festlegen.
Kann Empfangsunterbrechungen verarbeiten (siehe miniportInterrupt-Funktion ) und Interrupt-DPCs (siehe MiniportInterruptDPC-Funktion ), sollte jedoch keine empfangenen Netzwerkdaten angeben.
Kann status Hinweise mit der NdisMIndicateStatusEx-Funktion bereitstellen.
Sollte OID-Anforderungen in der MiniportOidRequest-Funktion verarbeiten.
Sollte Anforderungen behandeln, um den Energiezustand des Geräts in der MiniportDevicePnPEventNotify-Funktion .
Kann Aufrufe von NetTimerCallback-Funktionen verarbeiten.
Kann Anforderungen zum Zurücksetzen der Hardware in der MiniportResetEx-Funktion verarbeiten.

Miniport-Treiber können bei einer Pausenanforderung nicht fehlschlagen. Wenn ein Miniporttreiber daher Ressourcen zum Verarbeiten einer Pausenanforderung benötigt, sollte er die Ressourcen während der Initialisierung vorab zuweisen.

NDIS ruft die MiniportRestart-Funktion auf, um eine Neustartanforderung für einen angehaltenen Miniportadapter zu initiieren.

NDIS ruft MiniportPause bei IRQL = PASSIVE_LEVEL auf.

Beispiele

Um eine MiniportPause-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten 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 MiniportPause-Funktion mit dem Namen "MyPause" zu definieren, verwenden Sie den typ MINIPORT_PAUSE , wie in diesem Codebeispiel gezeigt:

MINIPORT_PAUSE MyPause;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyPause(
    NDIS_HANDLE  MiniportAdapterContext,
    PNDIS_MINIPORT_PAUSE_PARAMETERS  MiniportPauseParameters
    )
  {...}

Der MINIPORT_PAUSE Funktionstyp ist in der Headerdatei Ndis.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 MINIPORT_PAUSE 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.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt in NDIS 6.0 und höher.
Zielplattform	Windows
Kopfzeile	ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL