PROTOCOL_CL_OPEN_AF_COMPLETE_EX Rückruffunktion (ndis.h)

Artikel
08/07/2023

Die ProtocolClOpenAfCompleteEx-Funktion schließt das Öffnen einer Adressfamilie (AF) ab, die gestartet wurde, als ein CoNDIS-Client die NdisClOpenAddressFamilyEx-Funktion aufgerufen hat.

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

Syntax

PROTOCOL_CL_OPEN_AF_COMPLETE_EX ProtocolClOpenAfCompleteEx;

void ProtocolClOpenAfCompleteEx(
  [in] NDIS_HANDLE ProtocolAfContext,
  [in] NDIS_HANDLE NdisAfHandle,
  [in] NDIS_STATUS Status
)
{...}

Parameter

[in] ProtocolAfContext

Ein vom Client bereitgestelltes Handle für seinen Kontextbereich für einen Adress-AF. Der Client hat diesen Kontextbereich zugewiesen und dieses Handle in seinem Aufruf an die NDIS übergeben. NdisClOpenAddressFamilyEx-Funktion .

[in] NdisAfHandle

Ein von NDIS bereitgestelltes Handle für einen AF, wenn Status NDIS_STATUS_SUCCESS ist. Andernfalls ist dieser Parameter NULL. Dieses Handle stellt eine Zuordnung dar, die NDIS zwischen dem Client und einem Anruf-Manager eingerichtet hat, der an einen CoNDIS-Miniportadapter gebunden ist. Wenn das Handle nicht NULL ist, muss der Client das Handle für die Verwendung in nachfolgenden Aufrufen der Funktionen NdisClXxx und NdisCoXxx speichern.

[in] Status

Der letzte status des Aufrufs des Clients an NdisClOpenAddressFamilyEx, der wie folgt aussehen kann:

NDIS_STATUS_SUCCESS

Der AF wurde geöffnet, sodass der Client seinen Zustand bei ProtocolAfContext initialisieren und das von NdisAfHandle zurückgegebene Handle in nachfolgenden Aufrufen von NdisClXxx - und NdisCoXxx-Funktionen wie NdisCoOidRequest verwenden kann.

NDIS_STATUS_RESOURCES

Der angeforderte Vorgang ist fehlgeschlagen, da NDIS oder der Anruf-Manager nicht genügend Arbeitsspeicher zuweisen oder den Zustand initialisieren konnte, den einer von ihnen verwendet, um das Öffnen des AF des Clients nachzuverfolgen, den ProtocolAfContext angibt.

NDIS_STATUS_FAILURE

Bei NDIS ist der Anruf möglicherweise aus einem der folgenden Gründe fehlgeschlagen:

Der angegebene AF entspricht keinem AF, der für den zugrunde liegenden Miniporttreiber registriert wurde, an den der Aufrufer gebunden ist.
Die Adapterbindung des Aufrufers wird geschlossen.
Der Anruf-Manager, der den angegebenen AF registriert hat, schließt seine Bindung an den zugrunde liegenden Miniportadapter.

Rückgabewert

Keine

Bemerkungen

Die ProtocolClOpenAfCompleteEx-Funktion ist für CoNDIS-Clients erforderlich. CoNDIS-Clients müssen ProtocolClOpenAfCompleteEx bereitstellen, um die asynchronen Vorgänge abzuschließen, die die Clients durch Aufrufen des NdisClOpenAddressFamilyEx-Funktion .

NDIS ruft ProtocolClOpenAfCompleteEx auf, um anzugeben, dass einige oder alle der folgenden Ereignisse aufgetreten sind:

Wenn alle Parameter des Clients ProtocolCoAfRegisterNotify-Funktion , die an die NdisClOpenAddressFamilyEx-Funktion übergeben wurde, war gültig. NDIS rief die ProtocolCmOpenAf-Funktion des Aufruf-Managers auf, der gerade den angegebenen AF bei NDIS registriert hat.
Der Aufruf-Manager hat die Spezifikation untersucht, die die ProtocolCoAfRegisterNotify-Funktion des Clients an NdisClOpenAddressFamilyEx am Parameter AddressFamily übergeben hat, und hat zurückgegeben, ob sie für diesen Aufruf-Manager an NDIS gültig war.

Wenn der Versuch des Clients, einen AF zu öffnen, fehlschlägt, bereinigt NDIS den gespeicherten Zustand, bevor ProtocolClOpenAfCompleteEx aufgerufen wird. In diesem Fall kann ProtocolClOpenAfCompleteEx die Ressourcen freigeben, die der Client für seinen Aufruf von NdisClOpenAddressFamilyEx zugewiesen hat, oder sie für die Wiederverwendung vorbereiten.

Andernfalls sollte ProtocolClOpenAfCompleteEx den vom Client bestimmten Zustand einrichten, den der Client für nachfolgende Vorgänge für den neu geöffneten AF benötigt. Insbesondere muss der Client das Handle aus dem NdisAfHandle-Parameter speichern, in der Regel im Kontextbereich ProtocolAfContext des Clients.

Wenn der Client eingehende Aufrufe akzeptiert, kann er einen SAP-Statusbereich (Access Point) pro Dienst zuordnen und die Funktion NdisClRegisterSap aufrufen. Wenn der Client ausgehende Aufrufe ausgibt, kann er einen VC-Zustandsbereich (Per-Virtual Connection) zuweisen und eine VC mit der NdisCoCreateVc-Funktion erstellen, um eine eingehende Anforderung von einem der eigenen Clients des Clients vorzubereiten, um einen ausgehenden Aufruf an einen Remoteknoten zu tätigen.

NDIS ruft ProtocolClOpenAfCompleteEx unter IRQL = PASSIVE_LEVEL auf.

Beispiele

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

PROTOCOL_CL_OPEN_AF_COMPLETE_EX MyClOpenAfCompleteEx;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
VOID
 MyClOpenAfCompleteEx(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  NdisAfHandle,
    NDIS_STATUS  Status
    )
  {...}

Der PROTOCOL_CL_OPEN_AF_COMPLETE_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_CL_OPEN_AF_COMPLETE_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