MINIPORT_HALT Rückruffunktion (ndis.h)

Artikel
08/07/2023

NDIS ruft die MiniportHaltEx-Funktion eines Miniporttreibers auf, um Ressourcen freizugeben, wenn ein Miniportadapter entfernt wird, und um die Hardware zu beenden. Diese Funktion versetzt den Miniport in den Zustand Angehalten, in dem kein anderer Rückruf erfolgen kann (einschließlich MiniportShutdownEx). Weitere Informationen zu Miniporttreiberzuständen finden Sie unter Status und Vorgänge des Miniportadapters.

Hinweis Sie müssen die Funktion mithilfe des typs MINIPORT_HALT deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

MINIPORT_HALT MiniportHalt;

void MiniportHalt(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] NDIS_HALT_ACTION HaltAction
)
{...}

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] HaltAction

Der Grund für das Anhalten des Miniportadapters. Es kann sich um einen der folgenden Werte handeln:

NdisHaltDeviceDisabled

NDIS hält den Miniportadapter als Reaktion auf eine Plug & Play (PnP) Remove-Nachricht an.

NdisHaltDeviceInstanceDeInitialized

NDIS hält den Miniportadapter als Reaktion auf einen Zwischentreiber an, der die NdisIMDeInitializeDeviceInstance-Funktion .

NdisHaltDevicePoweredDown

NDIS hält den Miniportadapter an, da das System in einen Ruhezustand wechselt.

NdisHaltDeviceSurpriseRemoved

Der Miniportadapter wurde überraschend entfernt, und die Hardware ist nicht vorhanden.

NdisHaltDeviceFailed

Der Miniportadapter wird aufgrund eines Hardwarefehlers entfernt. Entweder der Miniporttreiber, der die NdisMRemoveMiniport-Funktion genannt hat, oder ein Bustreiber hat die NIC beim Fortsetzen nicht eingeschaltet.

NdisHaltDeviceInitializationFailed

NDIS konnte den Miniportadapter aus einem unbekannten Grund nicht initialisieren, nachdem die MiniportInitializeEx-Funktion erfolgreich abgeschlossen wurde.

NdisHaltDeviceStopped

NDIS hält den Miniportadapter als Reaktion auf eine PnP-Meldung zum Beenden des Geräts an.

Rückgabewert

Keine

Bemerkungen

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

NDIS kann MiniportHaltEx jederzeit aufrufen, nachdem die MiniportInitializeEx-Funktion eines Treibers erfolgreich zurückgegeben wurde. Wenn der Treiber eine physische NIC steuert, sollte MiniportHaltEx die NIC beenden. Wenn ein NDIS-Zwischentreiber den NdisIMDeInitializeDeviceInstance-Funktion , NDIS ruft die MiniportHaltEx-Funktion für das virtuelle Gerät des Treibers auf.

MiniportHaltEx muss alle Ressourcen freigeben, die in MiniportInitializeEx für ein Gerät zugeordnet wurden. MiniportHaltEx gibt auch alle anderen Ressourcen frei, die der Treiber in nachfolgenden Vorgängen für dieses Gerät zugewiesen hat. Der Treiber muss die Kehrfunktionen der NdisXxx-Funktionen aufrufen, denen er ursprünglich die Ressourcen zugeordnet hat. In der Regel sollte eine MiniportHaltEx-Funktion die NdisXxx-Funktionen in umgekehrter Reihenfolge zu den Aufrufen des Treibers von MiniportInitializeEx aufrufen.

Wenn eine NIC Interrupts generiert, kann die MiniportHaltEx-Funktion eines Miniport-Treibers von der MiniportInterrupt-Funktion des Treibers vorzeitig entfernt werden, bis der MiniportHaltEx-Aufruf des Die NdisMDeregisterInterruptEx-Funktion gibt zurück. Eine solche MiniportHaltEx-Funktion des Treibers sollte Unterbrechungen deaktivieren und aufrufen NdisMDeregisterInterruptEx so bald wie möglich. Beachten Sie, dass ein Treiber Unterbrechungen erhalten kann, bis NdisMDeregisterInterruptEx gibt zurück. NdisMDeregisterInterruptEx wird erst zurückgegeben, wenn der Treiber alle geplanten DPCs abgeschlossen hat (weitere Informationen finden Sie in der MiniportInterruptDPC-Funktion ).

Wenn der Treiber über eine NetTimerCallback-Funktion verfügt, die einem Timerobjekt zugeordnet ist, das sich in der Systemtimerwarteschlange befinden könnte, sollte MiniportHaltEx die NdisCancelTimerObject-Funktion aufrufen. Wenn NdisCancelTimerObject fehlschlägt , hat der Timer möglicherweise bereits ausgelöst. In diesem Fall sollte der Treiber warten, bis die Timerfunktion abgeschlossen ist, bevor der Treiber von MiniportHaltEx zurückkehrt.

NDIS ruft MiniportHaltEx nicht auf, wenn ausstehende OID-Anforderungen oder Sendeanforderungen vorliegen. NDIS sendet keine weiteren Anforderungen für das betroffene Gerät, nachdem NDIS MiniportHaltEx aufgerufen hat.

Wenn der Treiber auf den Abschluss eines Vorgangs warten muss, kann MiniportHaltEx die NdisWaitEvent-Funktion oder die NdisMSleep-Funktion verwenden.

NDIS ruft MiniportHaltEx am IRQL = PASSIVE_LEVEL auf.

Beispiele

Um eine MiniportHaltEx-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 MiniportHaltEx-Funktion mit dem Namen "MyHaltEx" zu definieren, verwenden Sie den typ MINIPORT_HALT , wie in diesem Codebeispiel gezeigt:

MINIPORT_HALT MyHaltEx;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
VOID
 MyHaltEx(
    NDIS_HANDLE  MiniportAdapterContext,
    NDIS_HALT_ACTION  HaltAction
    )
  {...}

Der MINIPORT_HALT Funktionstyp ist in der Ndis.h-Headerdatei 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_HALT 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
DDI-Complianceregeln	WlanAssociation, WlanConnectionRoaming, WlanDisassociation, WlanTimedAssociation, WlanTimedConnectionRoaming, WlanTimedConnectRequest, WlanTimedLinkQuality, WlanTimedScan