PROTOCOL_CM_REG_SAP Rückruffunktion (ndis.h)

Artikel
02/07/2025

Die ProtocolCmRegisterSap--Funktion ist eine erforderliche Funktion, die von NDIS aufgerufen wird, um anzufordern, dass ein Aufruf-Manager einen SAP (Dienstzugriffspunkt) im Auftrag eines verbindungsorientierten Clients registriert.

Hinweis Sie müssen die Funktion mithilfe des PROTOCOL_CM_REG_SAP-Typs deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt "Beispiele".

Syntax

PROTOCOL_CM_REG_SAP ProtocolCmRegSap;

NDIS_STATUS ProtocolCmRegSap(
  [in]  NDIS_HANDLE CallMgrAfContext,
  [in]  PCO_SAP Sap,
  [in]  NDIS_HANDLE NdisSapHandle,
  [out] PNDIS_HANDLE CallMgrSapContext
)
{...}

Parameter

[in] CallMgrAfContext

Gibt das Handle für einen kontextbezogenen Kontextbereich eines Anrufmanagers an, in dem der Anrufmanager seinen offenen AF-Zustand verwaltet. Der Anruf-Manager hat dieses Handle von der ProtocolCmOpenAf--Funktion an NDIS bereitgestellt.

[in] Sap

Zeiger auf eine medienspezifische CO_SAP-Struktur, die den spezifischen SAP enthält, den ein verbindungsorientierter Client registriert.

[in] NdisSapHandle

Gibt einen Handle an, der von NDIS bereitgestellt wird, der diese SAP eindeutig identifiziert. Dieses Handle ist für den Anruf-Manager undurchsichtig und für die Verwendung der NDIS-Bibliothek reserviert.

[out] CallMgrSapContext

Gibt den Handle für einen vom Anrufmanager bereitgestellten Kontextbereich an, in dem der Anrufmanager den Status dieses SAP verwaltet.

Rückgabewert

ProtocolCmRegisterSap- gibt den Status der vorgänge(n) wie folgt zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	Gibt an, dass der Anrufmanager alle erforderlichen Ressourcen erfolgreich zugeordnet und/oder initialisiert hat, um den SAP zu registrieren und zu verwalten. Darüber hinaus weist sie darauf hin, dass der SAP erfolgreich registriert wurde, wie es von den Netzwerkmedien benötigt wird, die der Anrufmanager unterstützt.
NDIS_STATUS_PENDING	Gibt an, dass der Anruf-Manager die Verarbeitung dieser Anforderung asynchron abschließen wird. Anrufmanager müssen anrufen NdisCmRegisterSapComplete, wenn die gesamte Verarbeitung abgeschlossen wurde, um NDIS zu signalisieren, dass die Registrierung abgeschlossen ist.
NDIS_STATUS_RESOURCES	Gibt an, dass der Anrufmanager seine Ressourcen nicht zugeordnet und/oder initialisieren konnte, die zum Registrieren des SAP im Namen des verbindungsorientierten Clients erforderlich sind.
NDIS_STATUS_INVALID_DATA	Gibt an, dass die unter Sap bereitgestellte Spezifikation ungültig oder nicht unterstützt werden kann.
NDIS_STATUS_XXX-	Gibt an, dass beim Versuch, den SAP für den verbindungsorientierten Client zu registrieren, ein Fehler aufgetreten ist. Der Rückgabecode ist für den Fehler geeignet und kann ein Rückgabecode sein, der von einer anderen NDIS-Bibliotheksfunktion weitergegeben wird.

Bemerkungen

ProtocolCmMakeCall kommuniziert bei Bedarf mit Netzwerksteuerungsgeräten oder anderen medienspezifischen Agents, um den SAP, wie bei Sapangegeben, für einen verbindungsorientierten Client zu registrieren. Solche Aktionen können u. a. die Kommunikation mit dem Wechsel der Hardware, die Kommunikation mit einer Netzwerksteuerungsstation oder andere Aktionen umfassen, die für das Netzwerkmedium geeignet sind.

Wenn ein Anrufmanager für die Kommunikation mit Netzwerksteuerungs-Agents (d. h. einem Netzwerkswitch) erforderlich ist, sollte er eine virtuelle Verbindung mit dem Netzwerksteuerungs-Agent verwenden, die er in seiner ProtocolBindAdapterEx--Funktion eingerichtet hat. Eigenständige Anrufmanager kommunizieren über den zugrunde liegenden Miniporttreiber, indem sie NdisCoSendNetBufferListsaufrufen. Miniport-Treiber mit integrierter Anrufverwaltungsunterstützung rufen nie NdisCoSendNetBufferLists. Stattdessen übertragen sie die Daten direkt über das Netzwerk.

Darüber hinaus sollten ProtocolCmRegisterSap- alle erforderlichen Zuordnungen dynamischer Ressourcen und Strukturen ausführen, die der Aufrufmanager benötigt, um Statusinformationen über den SAP im Auftrag des verbindungsorientierten Clients zu verwalten. Zu diesen Ressourcen gehören, jedoch nicht beschränkt auf Speicherpuffer, Datenstrukturen, Ereignisse und andere ähnliche Ressourcen. Ein Anrufmanager muss auch alle Ressourcen initialisieren, die er zuweist, bevor die Steuerung an NDIS zurückgegeben wird. Anrufmanager müssen den vom NDIS bereitgestellten Handle speichern, der den SAP identifiziert, der unter NdisSapHandlebereitgestellt wird, in ihrem Kontextbereich für die zukünftige Nutzung.

Wenn ProtocolCmRegisterSap- NDIS_STATUS_SUCCESS zurückgibt, sollte die Adresse dieses Zustandsbereichs nach dem Zuweisen des Statusbereichs pro SAP in CallMgrSapContext- festgelegt werden, bevor das Steuerelement an NDIS zurückgegeben wird. Führen Sie dazu die Ableitung CallMgrSapContext aus, und speichern Sie einen Zeiger auf den Datenbereich als Wert des Handles. Zum Beispiel:

*CallMgrSapContext = SomeBuffer ;

Wenn der angegebene SAP, der bereits von einem anderen verbindungsorientierten Client registriert ist, muss der Anrufmanager die Anforderung fehlschlagen und NDIS_STATUS_INVALID_DATA zurückgeben.

Nachdem ein Anrufmanager einen SAP im Namen eines verbindungsorientierten Clients registriert hat, benachrichtigt er den Kunden eines eingehenden Anrufangebots, das per Anruf an diesen SAP weitergeleitet wird. NdisCmDispatchIncomingCall.

beispiele für

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

PROTOCOL_CM_REG_SAP MyCmRegisterSap;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyCmRegisterSap(
    NDIS_HANDLE  CallMgrAfContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle,
    PNDIS_HANDLE  CallMgrSapContext
    )
  {...}

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