PROTOCOL_BIND_ADAPTER_EX Rückruffunktion (ndis.h)

Artikel
08/07/2023

NDIS ruft die ProtocolBindAdapterEx-Funktion eines Protokolltreibers auf, um den Treiber zur Bindung an einen Miniportadapter anzufordern.

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

Syntax

PROTOCOL_BIND_ADAPTER_EX ProtocolBindAdapterEx;

NDIS_STATUS ProtocolBindAdapterEx(
  [in] NDIS_HANDLE ProtocolDriverContext,
  [in] NDIS_HANDLE BindContext,
  [in] PNDIS_BIND_PARAMETERS BindParameters
)
{...}

Parameter

[in] ProtocolDriverContext

Ein Handle für einen vom Treiber zugewiesenen Kontextbereich, in dem der Treiber Zustands- und Konfigurationsinformationen verwaltet. Der Protokolltreiber hat diesen Kontextbereich an die NdisRegisterProtocolDriver-Funktion .

[in] BindContext

Das Handle, das den NDIS-Kontextbereich für diesen Bindungsvorgang identifiziert.

[in] BindParameters

Ein Zeiger auf eine NDIS_BIND_PARAMETERS Struktur, die von NDIS erstellt wurde.

Rückgabewert

ProtocolBindAdapterEx gibt einen der folgenden status Werte zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	ProtocolBindAdapterEx hat die Bindung an den zugrunde liegenden Miniportadapter erfolgreich abgeschlossen.
NDIS_STATUS_PENDING	ProtocolBindAdapterEx hat den Bindungsvorgang nicht abgeschlossen, und der Vorgang wird asynchron abgeschlossen. Der Protokolltreiber muss die NdisCompleteBindAdapterEx-Funktion , wenn der Vorgang abgeschlossen ist.
NDIS_STATUS_RESOURCES	ProtocolBindAdapterEx konnte die Ressourcen nicht zuordnen, die der Treiber für die Ausführung von Netzwerk-E/A-Vorgängen benötigt.
NDIS_STATUS_XXX oder NTSTATUS_XXX	Beim Versuch des Protokolltreibers, eine Bindung einzurichten, ist ein Fehler aufgetreten. Normalerweise wird ein solcher Fehler status von einer NdisXxx-Funktion oder einer Kernelmodusunterstützungsroutine weitergegeben.

Hinweise

ProtocolBindAdapterEx ist eine erforderliche Funktion. NDIS ruft ProtocolBindAdapterEx auf, um Bindungsvorgänge auszuführen, wenn ein zugrunde liegender Miniportadapter, an den der Protokolltreiber gebunden werden kann, verfügbar wird.

ProtocolBindAdapterEx weist genügend Arbeitsspeicher zu, um die Bindungskontextinformationen beizubehalten, und ruft die NdisOpenAdapterEx-Funktion auf, um sich an den zugrunde liegenden Miniportadapter zu binden. ProtocolBindAdapterEx übergibt einen Zeiger auf die Bindungskontextinformationen am ProtocolBindingContext-Parameter von NdisOpenAdapterEx. ProtocolBindAdapterEx übergibt den Wert am AdapterName-Member aus seinem BindParameters-Parameter als AdapterName-Member des OpenParameters-Parameters von NdisOpenAdapterEx.

Bevor der Treiber NdisOpenAdapterEx aufruft, kann der Treiber den Zeiger bei BindParameters an die NdisOpenConfigurationEx-Funktion übergeben, um die Konfigurationsparameter zu lesen, die einem Miniportadapter zugeordnet sind.

Nachdem der Miniportadapter erfolgreich geöffnet wurde, kann der Treiber das Handle vom NdisHandle-Parameter von NdisOpenAdapterEx an NdisOpenConfigurationEx übergeben, um ein Handle an den Registrierungsspeicherort abzurufen, in dem die Konfigurationsparameter für eine Protokollbindung gespeichert sind.

ProtocolBindAdapterEx übergibt NdisOpenAdapterEx einen Zeiger auf ein Array mittlerer Werte, das die Medientypen auflistet, die der Protokolltreiber unterstützen kann. Diese Liste ist eine Teilmenge der NDIS_MEDIUM Typen. NDIS gibt den ausgewählten mittleren Typ am SelectedMediumIndex-Parameter der Struktur bei OpenParameters an.

Wenn NdisOpenAdapterEx einen Fehler status zurückgibt, gibt ProtocolBindAdapterEx diesen Fehler status zurück, gibt alle vom Protokolltreiber zugewiesenen Ressourcen pro Bindung frei und gibt die Steuerung sofort zurück.

Wenn NdisOpenAdapterEx NDIS_STATUS_SUCCESS zurückgibt, kann ProtocolBindAdapterEx die verbleibenden Ressourcen zuordnen, die der Protokolltreiber zum Ausführen von Netzwerk-E/A für die Bindung benötigt. Der Treiber kann auch alle bindungsspezifischen Kontextinformationen konfigurieren, die der Treiber zum Nachverfolgen von Netzwerk-E/A-Vorgängen verwendet.

Wenn NdisOpenAdapterEx NDIS_STATUS_PENDING zurückgibt, ruft NDIS die des Protokolltreibers auf. ProtocolOpenAdapterCompleteEx-Funktion nach Abschluss des geöffneten Vorgangs. ProtocolOpenAdapterCompleteEx kann die Bindungsvorgänge abschließen. ProtocolBindAdapterEx kann das BindContext-Handle im Bindungskontextbereich speichern. NDIS übergibt ProtocolBindingContext als Eingabeparameter an die ProtocolOpenAdapterCompleteEx-Funktion des Treibers.

Wenn NdisOpenAdapterEx NDIS_STATUS_PENDING zurückgibt, legt NDIS das SelectedMediumIndex-Element der Struktur am OpenParameters-Parameter und den Wert des NdisBindingHandle-Parameters nach NdisOpenAdapterEx fest. NDIS legt diese Werte vor dem Aufrufen von ProtocolOpenAdapterCompleteEx fest. Daher muss der Protokolltreiber die offene Parameterstruktur und das Protokollbindungshandle im Kontextbereich unter ProtocolBindingContext(oder an einem beliebigen Speicherort speichern, der gültig ist, bis NDIS ProtocolOpenAdapterCompleteEx aufruft).

Ein Protokolltreiber kann keine OID-Anforderungen für eine Bindung stellen, bis der geöffnete Vorgang abgeschlossen ist. Da sich die Bindung nach Abschluss des geöffneten Vorgangs im angehaltenen Zustand befindet, kann der Protokolltreiber keine Sendeanforderungen stellen, bis NDIS die Bindung neu gestartet hat.

Nach Abschluss des geöffneten Vorgangs kann ProtocolBindAdapterEx NDIS_STATUS_SUCCESS zurückgeben, um den Bindungsvorgang abzuschließen. ProtocolBindAdapterEx kann NDIS_STATUS_PENDING zurückgeben, um den Abschluss der Bindungsvorgänge auf einen späteren Zeitpunkt zu verschieben. Wenn ProtocolBindAdapterEx NDIS_STATUS_PENDING zurückgibt, muss der Treiber die NdisCompleteBindAdapterEx-Funktion , nachdem der Bindungsvorgang abgeschlossen ist.

Protokolltreiber sollten die NDIS_BIND_PARAMETERS-Struktur verwenden, um die Funktionen des zugrunde liegenden Miniportadapters zu bestimmen. Nach Abschluss des geöffneten Vorgangs kann der Protokolltreiber abhängig vom zugrunde liegenden Medium die NdisOidRequest-Funktion aufrufen, um den zugrunde liegenden Miniporttreiber (oder NDIS) nach zusätzlichen Miniportadapterfunktionen abzufragen. Weitere Informationen zu OID-Anforderungen finden Sie unter Protokolltreiber-OID-Anforderungen.

NDIS kann die Eines Protokolltreibers aufrufen ProtocolReceiveNetBufferLists-Funktion , nachdem der Treiber einen Paketfilter für die Bindung mit dem eingerichtet hat OID_GEN_CURRENT_PACKET_FILTER OID. Wenn der zugrunde liegende Miniportadapter keinen Paketfilter für eingehende Pakete verwendet, werden Empfangsanzeigen nach Abschluss des geöffneten Vorgangs aktiviert. Protokolltreiber können status Hinweise auf die ProtocolStatusEx-Funktion empfangen, nachdem der geöffnete Vorgang abgeschlossen ist.

Jeder Protokolltreiber sollte ausreichend NET_BUFFER und NET_BUFFER_LIST Strukturpools zuordnen. Der Treiber weist Netzwerkdatendeskriptoren aus diesen Pools für nachfolgende Sendevorgänge zu.

Wenn ProtocolBindAdapterEx die Ressourcen nicht zuordnen kann, die es für nachfolgende Netzwerk-E/A-Vorgänge benötigt, sollte es alle Ressourcen freigeben, die bereits zugewiesen wurden, und einen entsprechenden Fehlerwert zurückgeben.

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

Wenn der Protokolltreiber den Miniportadapter erfolgreich öffnet, der Bindungsvorgang jedoch fehlschlägt (z. B. aufgrund einer fehlerhaften OID-Anforderung), muss der Treiber den Miniportadapter im Kontext von ProtocolBindAdapterEx oder ProtocolUnbindAdapterEx schließen. Beispielsweise ruft der Treiber NdisCloseAdapterEx von ProtocolBindAdapterEx auf und wartet, bis der Schließenvorgang abgeschlossen ist, bevor der Treiber von ProtocolBindAdapterEx zurückkehrt. Wenn der Treiber NDIS_STATUS_PENDING von ProtocolBindAdapterEx zurückgegeben hat, kann der Treiber alternativ die NdisUnbindAdapter-Funktion aufrufen und NdisCloseAdapterEx in der ProtocolUnbindAdapterEx-Funktion aufrufen.

NDIS ruft ProtocolBindAdapterEx unter IRQL = PASSIVE_LEVEL auf.

Beispiele

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

PROTOCOL_BIND_ADAPTER_EX MyBindAdapterEx;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyBindAdapterEx(
    NDIS_HANDLE  ProtocolDriverContext,
    NDIS_HANDLE  BindContext,
    PNDIS_BIND_PARAMETERS  BindParameters
    )
  {...}

Der PROTOCOL_BIND_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_BIND_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 in NDIS 6.0 und höher.
Zielplattform	Windows
Kopfzeile	ndis.h (einschließlich Ndis.h)
IRQL	PASSIVE_LEVEL