PROTOCOL_UNBIND_ADAPTER_EX Rückruffunktion (ndis.h)

Artikel
02/26/2024

NDIS ruft die ProtocolUnbindAdapterEx-Funktion eines Protokolltreibers auf, um den Treiber aufzufordern, die Bindung von einem zugrunde liegenden Miniportadapter aufzuheben.

Hinweis Sie müssen die Funktion mit dem PROTOCOL_UNBIND_ADAPTER_EX-Typ deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

PROTOCOL_UNBIND_ADAPTER_EX ProtocolUnbindAdapterEx;

NDIS_STATUS ProtocolUnbindAdapterEx(
  [in] NDIS_HANDLE UnbindContext,
  [in] NDIS_HANDLE ProtocolBindingContext
)
{...}

Parameter

[in] UnbindContext

Das Handle, das den NDIS-Kontextbereich für diesen nicht bindungslosen Vorgang identifiziert.

[in] ProtocolBindingContext

Ein Handle für einen Kontextbereich, der vom Protokolltreiber zugeordnet ist. Der Protokolltreiber verwaltet die Kontextinformationen pro Bindung in diesem Kontextbereich. Der Treiber hat dieses Handle für NDIS bereitgestellt, wenn der Treiber die NdisOpenAdapterEx-Funktion aufgerufen hat.

Rückgabewert

ProtocolUnbindAdapterEx gibt einen der folgenden status Werte zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	ProtocolUnbindAdapterEx wurde erfolgreich von einem zugrunde liegenden Miniportadapter getrennt.
NDIS_STATUS_PENDING	ProtocolUnbindAdapterEx hat den Nichtbindungsvorgang nicht abgeschlossen, und der Vorgang wird asynchron abgeschlossen. Der Protokolltreiber muss die NdisCompleteUnbindAdapterEx-Funktion , nachdem der Vorgang zum Aufheben der Bindung abgeschlossen ist.

Hinweise

ProtocolUnbindAdapterEx ist eine erforderliche Funktion. Als Reziproz der ProtocolBindAdapterEx-Funktion ruft NDIS ProtocolUnbindAdapterEx auf, um die Ressourcen freizugeben, die der Treiber für Netzwerk-E/A-Vorgänge zugewiesen hat, die für eine Bindung spezifisch sind. Ein Protokolltreiber kann bei einem nicht bindungslosen Vorgang nicht fehlschlagen.

Vor dem Aufrufen von ProtocolUnbindAdapterEx hält NDIS die Protokollbindung an. Um die Bindung anzuhalten, ruft NDIS die ProtocolNetPnPEvent-Funktion auf und legt ein NetEventPause-Ereignis fest.

ProtocolUnbindAdapterEx muss die NdisCloseAdapterEx-Funktion aufrufen, um die Bindung an den zugrunde liegenden Miniportadapter zu schließen. Wenn NdisCloseAdapterEx NDIS_STATUS_SUCCESS zurückgibt, ist der Schließenvorgang abgeschlossen. Wenn NdisCloseAdapterEx NDIS_STATUS_PENDING zurückgibt, ruft NDIS die des Protokolltreibers auf. ProtocolCloseAdapterCompleteEx-Funktion nach Abschluss des Vorgangs zum Schließen.

Vor dem Aufrufen von NdisCloseAdapterEx sollte der Protokolltreiber die Multicastadressenliste und die Paketfilter für die Bindung löschen. Der Protokolltreiber legt die Bindungs-Multicastadressliste auf NULL und den Paketfilter auf Null fest. Weitere Informationen finden Sie unter OID_802_3_MULTICAST_LIST und OID_GEN_CURRENT_PACKET_FILTER.

Wenn ein Aktivierungsmuster angegeben wurde, sollte der Protokolltreiber es mit der OID_PNP_REMOVE_WAKE_UP_PATTERN OID entfernen und die empfangsseitigen Skalierungsparameter mit der OID_GEN_RECEIVE_SCALE_PARAMETERS OID löschen. Ein NDIS 6.20- und höher-Protokolltreiber sollte ein Wake-on-LAN-Muster mit der OID_PM_REMOVE_WOL_PATTERN OID entfernen und eine Protokollauslagerung mit geringer Leistung mit der OID_PM_REMOVE_PROTOCOL_OFFLOAD OID entfernen.

ProtocolUnbindAdapterEx darf den Arbeitsspeicher bei ProtocolBindingContext erst freigeben, wenn der Abschlussvorgang abgeschlossen ist. NDIS übergibt das Handle unter ProtocolBindingContext an ProtocolCloseAdapterCompleteEx.

Wenn der Protokolltreiber den vorgang ohne Bindung abgeschlossen hat, kann ProtocolUnbindAdapterEx NDIS_STATUS_SUCCESS zurückgeben. Wenn NdisCloseAdapterEx NDIS_STATUS_PENDING zurückgibt, muss ProtocolUnbindAdapterEx warten, bis NDIS ProtocolCloseAdapterCompleteEx aufruft , bevor NDIS_STATUS_SUCCESS zurückgegeben werden kann.

ProtocolUnbindAdapterEx kann NDIS_STATUS_PENDING zurückgeben, um den Abschluss des nicht bindungslosen Vorgangs auf einen späteren Zeitpunkt zu verschieben. Wenn ProtocolUnbindAdapterEx NDIS_STATUS_PENDING zurückgibt, muss der Treiber schließlich den NdisCompleteUnbindAdapterEx-Funktion , um den Vorgang für die Bindungsentbindung abzuschließen. Wenn die NdisCloseAdapterEx-Funktion NDIS_STATUS_PENDING zurückgegeben hat, kann der Treiber den Vorgang zum Aufheben der Bindung in ProtocolCloseAdapterCompleteEx abschließen. ProtocolUnbindAdapterEx kann das Handle bei UnbindContext im Kontextbereich von ProtocolBindingContext speichern, bevor NdisCloseAdapterEx aufgerufen wird. Wenn ProtocolUnbindAdapterEx das Handle gespeichert hat, kann ProtocolCloseAdapterCompleteEx das Handle an NdisCompleteUnbindAdapterEx übergeben, um den vorgang ohne Bindung abzuschließen.

Sobald ProtocolUnbindAdapterExNdisCloseAdapterEx aufruft, wird das von der NdisOpenAdapterEx-Funktion am Parameter NdisBindingHandle abgerufene Handle ungültig. ProtocolUnbindAdapterEx kann mit diesem Handle keine nachfolgenden Aufrufe von NdisXxx-Funktionen ausführen. Der Treiber kann Empfangs- und status-Hinweise vom zugrunde liegenden Miniportadapter erhalten, bis der Abschlussvorgang abgeschlossen ist.

NDIS ruft ProtocolUnbindAdapterEx unter IRQL = PASSIVE_LEVEL auf.

Aktualisieren von Energieverwaltungs- und RSS-Einstellungen

Die NDIS 6.0- und 6.1-Protokolltreiber sollten gegebenenfalls die folgenden Vorgänge ausführen:

Entfernen Sie die Muster für die Energieverwaltungsreaktivierung in LAN (WOL) aus dem Miniportadapter mit dem OID_PNP_REMOVE_WAKE_UP_PATTERN OID.
Löschen Sie die empfangsseitigen Skalierungsparameter mit dem OID_GEN_RECEIVE_SCALE_PARAMETERS OID.

NDIS 6.20 und höher sollten die folgenden Vorgänge ausführen:

Entfernen Sie WOL-Muster für die Energieverwaltung aus dem Miniportadapter mit der OID_PM_REMOVE_WOL_PATTERN OID.
Entfernen Sie die Auslagerungen des Energieverwaltungsprotokolls vom Miniportadapter mit dem OID_PM_REMOVE_PROTOCOL_OFFLOAD OID.

Beispiele

Um eine ProtocolUnbindAdapterEx-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der zu definierenden Funktion identifiziert. Windows stellt eine Reihe von Funktionstypen für Treiber bereit. 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 Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine ProtocolUnbindAdapterEx-Funktion mit dem Namen "MyUnbindAdapterEx" zu definieren, verwenden Sie den typ PROTOCOL_UNBIND_ADAPTER_EX , wie in diesem Codebeispiel gezeigt:

PROTOCOL_UNBIND_ADAPTER_EX MyUnbindAdapterEx;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyUnbindAdapterEx(
    NDIS_HANDLE  UnbindContext,
    NDIS_HANDLE  ProtocolBindingContext
    )
  {...}

Der PROTOCOL_UNBIND_ADAPTER_EX Funktionstyp ist in der Headerdatei Ndis.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzu. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den PROTOCOL_UNBIND_ADAPTER_EX 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 für NDIS 6.0 und höher.
Zielplattform	Windows
Kopfzeile	ndis.h (einschließlich Ndis.h)
IRQL	PASSIVE_LEVEL