PROTOCOL_CM_OPEN_AF Rückruffunktion (ndis.h)

Artikel
02/07/2025

Die ProtocolCmOpenAf--Funktion ist erforderlich. Diese Funktion weist ressourcenbasierte Ressourcen für einen Anrufmanager zu, um mit einem verbindungsorientierten NDIS-Client zu interagieren, der die Adressfamilie öffnet.

Note You must declare the function by using the PROTOCOL_CM_OPEN_AF type. Weitere Informationen finden Sie im folgenden Abschnitt "Beispiele".

Syntax

PROTOCOL_CM_OPEN_AF ProtocolCmOpenAf;

NDIS_STATUS ProtocolCmOpenAf(
  [in]  NDIS_HANDLE CallMgrBindingContext,
  [in]  PCO_ADDRESS_FAMILY AddressFamily,
  [in]  NDIS_HANDLE NdisAfHandle,
  [out] PNDIS_HANDLE CallMgrAfContext
)
{...}

Parameter

[in] CallMgrBindingContext

Für einen nicht integrierten Anrufmanager gibt CallMgrBindingContext das Handle für einen Kontextbereich mit Anruf-Manager zugewiesen an, in dem die Anrufmanager ihre Informationen über den Bindungsstatus verwalten. Der Anruf-Manager hat diesen Handle bereitgestellt, wenn er NdisOpenAdapterExaufgerufen hat.

Für einen integrierten Anrufmanager (MCM) gibt CallMgrBindingContext- den Handle für einen miniportgeteilten Kontextbereich an, in dem der Miniport seine Statusinformationen pro Adapter verwaltet. Der Miniport hat dieses Handle in seinem NdisMSetAttributesEx-aufruf (für 5,x-Treiber) oder in seinen NdisMSetMiniportAttributes Aufruf (für 6.x-Treiber) bereitgestellt.

[in] AddressFamily

Gibt die Adressfamilie an, die ein Client öffnet. Diese Adressfamilie wurde vom Anrufmanager beim Aufrufen registriert. NdisCmRegisterAddressFamilyEx.

[in] NdisAfHandle

Gibt ein Handle an, das von NDIS bereitgestellt wird und diese Adressfamilieninstanz eindeutig identifiziert. Dieses Handle ist für den Anruf-Manager undurchsichtig und für die Systemverwendung reserviert.

[out] CallMgrAfContext

Gibt das Handle für einen vom Anruf-Manager bereitgestellten Kontextbereich an, in dem der Anrufmanager den Status über diese geöffnete Adressfamilie verwaltet.

Rückgabewert

ProtocolCmOpenAf gibt den Status seiner Vorgänge als eine der folgenden Aktionen zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	Gibt an, dass der Anrufmanager alle Ressourcen erfolgreich zugeordnet und initialisiert hat, die zum Annehmen von Anforderungen vom Client an diese Adressfamilie erforderlich sind.
NDIS_STATUS_PENDING	Gibt an, dass der angeforderte Vorgang asynchron behandelt wird. Der Anrufmanager muss anrufen NdisCmOpenAddressFamilyComplete, wenn alle Open-AF-Vorgänge abgeschlossen wurden, um NDIS (und den Client) anzugeben, dass die Vorgänge abgeschlossen wurden.
NDIS_STATUS_RESOURCES	Gibt an, dass der Anrufmanager seine erforderlichen Vorgänge aufgrund eines Mangels an verfügbaren Systemressourcen, z. B. Arbeitsspeicher, nicht abschließen konnte.
NDIS_STATUS_XXX-	Gibt an, dass der Anrufmanager sich nicht in einen Zustand setzen konnte, in dem er Anfragen vom Client akzeptieren kann, um mit dieser Adressfamilie zu arbeiten. Dies kann ein Fehlerstatus sein, der von einer anderen NDIS-Bibliotheksfunktion oder einem fehlerstatus weitergegeben wird, der vom Treiberschreiber entsprechend bestimmt wurde.

Bemerkungen

ProtocolCmOpenAf alle erforderlichen Zuordnungen dynamischer Ressourcen und Strukturen durchführt, die der Anruf-Manager-Writer für die Ausführung von Vorgängen im Auftrag des Clients, der eine Instanz dieser Adressfamilie öffnet, als notwendig erachtet. Zu diesen Ressourcen gehören, jedoch nicht beschränkt auf Speicherpuffer, Datenstrukturen, Ereignisse und andere ähnliche Ressourcen. Ein Anrufmanager sollte auch alle relevanten daten pro geöffneten Daten initialisieren, bevor die Steuerung an NDIS zurückgegeben wird.

Wenn ein Anrufmanager seinen zustandsspezifischen Bereich zugewiesen hat, sollte die Adresse des Statusbereichs im CallMgrAfContext- Handle festgelegt werden, bevor die Steuerung an NDIS zurückgegeben wird. Führen Sie hierzu die Ableitung CallMgrAfContext aus, und speichern Sie einen Zeiger auf den Datenbereich als Wert des Handles. Zum Beispiel:

*CallMgrAfContext = SomeBuffer;

Wenn ProtocolCmOpenAf die pro geöffneten Ressourcen nicht zuordnen kann, die sie benötigt, um nachfolgende Anforderungen im Auftrag des Clients auszuführen, der diese Adressfamilie öffnet, sollte sie alle Ressourcen freigeben, die sie für das öffnende Steuerelement zugewiesen haben, und die NDIS mit NDIS_STATUS_RESOURCES zurückgeben.

Wenn ProtocolCmOpenAf die erforderlichen Vorgänge abgeschlossen hat und die CM bereit ist, Anforderungen vom Client zu akzeptieren, sollte ProtocolCmOpenAf die Steuerung so schnell wie möglich mit einem Status von NDIS_STATUS_SUCCESS zurückgeben.

beispiele für

Um eine ProtocolCmOpenAf--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 ProtocolCmOpenAf--Funktion zu definieren, die den Namen "MyCmOpenAf" hat, verwenden Sie den PROTOCOL_CM_OPEN_AF Typ, wie in diesem Codebeispiel gezeigt:

PROTOCOL_CM_OPEN_AF MyCmOpenAf;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyCmOpenAf(
    NDIS_HANDLE  CallMgrBindingContext,
    PCO_ADDRESS_FAMILY  AddressFamily,
    NDIS_HANDLE  NdisAfHandle,
    PNDIS_HANDLE  CallMgrAfContext
    )
  {...}

Der PROTOCOL_CM_OPEN_AF 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_CM_OPEN_AF 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 für NDIS 6.0- und NDIS 5.1-Treiber (siehe ProtocolCmOpenAf (NDIS 5.1)) in Windows Vista. Unterstützt für NDIS 5.1-Treiber (siehe ProtocolCmOpenAf (NDIS 5.1)) in Windows XP.
Zielplattform-	Fenster
Header-	ndis.h (include Ndis.h)
IRQL-	<= DISPATCH_LEVEL

Siehe auch

NdisClOpenAddressFamilyEx

NdisCmOpenAddressFamilyComplete NdisCmRegisterAddressFamilyEx

NdisOpenAdapterEx

Freigeben über