PROTOCOL_BIND_ADAPTER_EX Rückruffunktion (ndis.h)
NDIS ruft die ProtocolBindAdapterEx--Funktion eines Protokolltreibers auf, um den Treiber anzufordern, eine Bindung an einen Miniportadapter durchzuführen.
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 den 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 NDIS erstellt hat.
Rückgabewert
ProtocolBindAdapterEx gibt einen der folgenden Statuswerte zurück:
| Rückgabecode | Beschreibung |
|---|---|
|
ProtocolBindAdapterEx die Bindung an den zugrunde liegenden Miniportadapter erfolgreich abgeschlossen. |
|
ProtocolBindAdapterEx den Bindungsvorgang nicht abgeschlossen und der Vorgang wird asynchron abgeschlossen. Der Protokolltreiber muss die NdisCompleteBindAdapterEx Funktion, wenn der Vorgang abgeschlossen ist. |
|
ProtocolBindAdapterEx- konnte die Ressourcen, die der Treiber zum Ausführen von Netzwerk-E/A-Vorgängen benötigt, nicht zuordnen. |
|
Fehler beim Versuch des Protokolltreibers, eine Bindung einzurichten. In der Regel wird ein solcher Fehlerstatus von einer NdisXxx--Funktion oder einer Kernelmodusunterstützungsroutine weitergegeben. |
Bemerkungen
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 ausreichend 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 an die Bindungskontextinformationen an den Parameter ProtocolBindingContext Parameter von NdisOpenAdapterEx. ProtocolBindAdapterEx den Wert an das AdapterName Member aus dem BindParameters Parameter als AdapterName Member des OpenParameters Parameter von NdisOpenAdapterExübergibt.
Bevor der Treiber NdisOpenAdapterExaufruft, kann der Treiber den Zeiger an BindParameters an die NdisOpenConfigurationEx--Funktion übergeben, um die Konfigurationsparameter zu lesen, die einem Miniportadapter zugeordnet sind.
Nach dem erfolgreichen Öffnen des Miniportadapters kann der Treiber das Handle von NdisHandle Parameter von NdisOpenAdapterEx an NdisOpenConfigurationEx übergeben, um ein Handle an den Registrierungsspeicherort abzurufen, an dem die Konfigurationsparameter für eine Protokollbindung gespeichert sind.
ProtocolBindAdapterEx übergibt NdisOpenAdapterEx einen Zeiger auf ein Array mittlerer Typwerte, die die vom Protokolltreiber unterstützten Medientypen auflisten. Diese Liste ist eine Teilmenge der NDIS_MEDIUM Typen. NDIS gibt den ausgewählten mittleren Typ am SelectedMediumIndex Parameter der Struktur bei OpenParametersan.
Wenn NdisOpenAdapterEx einen Fehlerstatus zurückgibt, gibt ProtocolBindAdapterEx diesen Fehlerstatus zurück, gibt alle bindungsbezogenen Ressourcen frei, die der Protokolltreiber zugeordnet hat, und gibt die Steuerung sofort zurück.
Wenn NdisOpenAdapterEx NDIS_STATUS_SUCCESS zurückgibt, kann ProtocolBindAdapterEx die verbleibenden Ressourcen zuordnen, die der Protokolltreiber für die Bindung ausführen muss. Der Treiber kann auch bindungsspezifische Kontextinformationen konfigurieren, die der Treiber zum Nachverfolgen von Netzwerk-E/A-Vorgängen verwendet.
Wenn NdisOpenAdapterEx NDIS_STATUS_PENDING zurückgibt, ruft NDIS den Protokolltreiber auf. ProtocolOpenAdapterCompleteEx-Funktion nach Abschluss des Öffnenvorgangs. ProtocolOpenAdapterCompleteEx- kann die Bindungsvorgänge ausführen. 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 fest, nachdem NdisOpenAdapterEx zurückgegeben wird. NDIS legt diese Werte vor dem Aufrufen ProtocolOpenAdapterCompleteEx-fest. Daher muss der Protokolltreiber die Struktur der offenen Parameter speichern und das Protokollbindungshandle im Kontextbereich bei ProtocolBindingContext-(oder eines beliebigen gültigen Speicherorts, bis NDIS ProtocolOpenAdapterCompleteExaufruft).
Ein Protokolltreiber kann OID-Anforderungen für eine Bindung erst ausführen, wenn der Öffnenvorgang abgeschlossen ist. Da sich die Bindung nach Abschluss des Geöffneten Vorgangs im angehaltenen Zustand befindet, kann der Protokolltreiber Erst nach dem Neustart der NDIS-Bindung Sendeanforderungen senden.
Nach Abschluss des Öffnens 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 zu einem späteren Zeitpunkt zu verzögern. Wenn ProtocolBindAdapterEx NDIS_STATUS_PENDING zurückgibt, muss der Treiber die NdisCompleteBindAdapterEx Funktion nach Abschluss des Bindungsvorgangs.
Protokolltreiber sollten die NDIS_BIND_PARAMETERS Struktur verwenden, um die Funktionen des zugrunde liegenden Miniportadapters zu ermitteln. Nach Abschluss des Geöffneten Vorgangs kann der Protokolltreiber abhängig von den zugrunde liegenden Medien die NdisOidRequest--Funktion aufrufen, um den zugrunde liegenden Miniporttreiber (oder NDIS) über zusätzliche Miniportadapterfunktionen abzufragen. Weitere Informationen zu OID-Anforderungen finden Sie unter Protokolltreiber-OID-Anforderungen.
NDIS kann die Protokolltreiber aufrufen ProtocolReceiveNetBufferLists Funktion, nachdem der Treiber einen Paketfilter für die Bindung mit der OID_GEN_CURRENT_PACKET_FILTER OID. Wenn der zugrunde liegende Miniportadapter keinen Paketfilter für eingehende Pakete verwendet, werden Die Empfangsanzeigen nach Abschluss des Geöffneten Vorgangs aktiviert. Protokolltreiber können Statusanzeigen an der ProtocolStatusEx--Funktion empfangen, nachdem der Öffnenvorgang abgeschlossen ist.
Jeder Protokolltreiber sollte ausreichende 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 für nachfolgende Netzwerk-E/A-Vorgänge erforderlich sind, sollte sie alle bereits zugeordneten Ressourcen freigeben und einen entsprechenden Fehlerwert zurückgeben.
NDIS ruft die Protokolltreiber auf ProtocolUnbindAdapterEx--Funktion, um den Treiber von einem zugrunde liegenden Miniportadapter abzubinden.
Wenn der Protokolltreiber den Miniportadapter erfolgreich öffnet, aber der Bindungsvorgang fehlschlägt (z. B. aufgrund einer fehlgeschlagenen OID-Anforderung), muss der Treiber den Miniportadapter im Kontext von ProtocolBindAdapterEx oder ProtocolUnbindAdapterExschließen. Beispielsweise ruft der Treiber NdisCloseAdapterEx von ProtocolBindAdapterEx auf und wartet, bis der Schließenvorgang abgeschlossen ist, bevor der Treiber von ProtocolBindAdapterExzurückgegeben wird. Wenn der treiber NDIS_STATUS_PENDING von ProtocolBindAdapterExzurückgegeben wurde, kann der Treiber die NdisUnbindAdapter-Funktion aufrufen und NdisCloseAdapterEx- in der ProtocolUnbindAdapterEx--Funktion aufrufen.
NDIS ruft ProtocolBindAdapterEx- bei IRQL = PASSIVE_LEVEL auf.
beispiele für
Um eine ProtocolBindAdapterEx--Funktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der Funktion identifiziert, die Sie definieren. Windows stellt eine Reihe von Funktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Funktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.Um beispielsweise eine ProtocolBindAdapterEx--Funktion zu definieren, die den Namen "MyBindAdapterEx" hat, verwenden Sie den PROTOCOL_BIND_ADAPTER_EX Typ, 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 wird in der Ndis.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzufügen. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen, die auf den Funktionstyp PROTOCOL_BIND_ADAPTER_EX in der Headerdatei angewendet werden, verwendet 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_annotationsfinden Sie unter Annotating Function Behavior.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Unterstützt in NDIS 6.0 und höher. |
| Zielplattform- | Fenster |
| Header- | ndis.h (include Ndis.h) |
| IRQL- | PASSIVE_LEVEL |