PROTOCOL_CM_REG_SAP Rückruffunktion (ndis.h)

Artikel
02/29/2024

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

Hinweis Sie müssen die Funktion mit dem PROTOCOL_CM_REG_SAP-Typ 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 vom Anruf-Manager zugewiesenen Kontextbereich an, in dem der Anruf-Manager seinen af-Zustand pro geöffneter Instanz beibehält. Der Aufruf-Manager hat dieses Handle über seine ProtocolCmOpenAf-Funktion an NDIS bereitgestellt.

[in] Sap

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

[in] NdisSapHandle

Gibt ein von NDIS bereitgestelltes Handle an, das 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 bei der Rückgabe das Handle für einen vom Anruf-Manager bereitgestellten Kontextbereich an, in dem der Anruf-Manager den Zustand dieser SAP verwaltet.

Rückgabewert

ProtocolCmRegisterSap gibt den status seiner Vorgänge wie folgt zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	Gibt an, dass der Anruf-Manager alle erforderlichen Ressourcen erfolgreich zugewiesen und/oder initialisiert hat, um SAP zu registrieren und zu verwalten. Darüber hinaus gibt es auch an, dass die SAP erfolgreich registriert wurde, wie von den Netzwerkmedien erforderlich, die vom Anruf-Manager unterstützt werden.
NDIS_STATUS_PENDING	Gibt an, dass der Anruf-Manager die Verarbeitung dieser Anforderung asynchron abschließt. 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 Anruf-Manager seine Ressourcen nicht zuordnen und/oder initialisieren konnte, die für die Registrierung der SAP im Namen des verbindungsorientierten Clients erforderlich sind.
NDIS_STATUS_INVALID_DATA	Gibt an, dass die in Sap bereitgestellte Spezifikation ungültig ist oder nicht unterstützt werden kann.
NDIS_STATUS_XXX	Gibt an, dass beim Versuch, 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.

Hinweise

ProtocolCmMakeCall kommuniziert bei Bedarf mit Netzwerksteuerungsgeräten oder anderen medienspezifischen Agents, um die SAP, wie bei Sap angegeben, im Netzwerk für einen verbindungsorientierten Client zu registrieren. Solche Aktionen können unter anderem die Kommunikation mit der Wechselhardware, die Kommunikation mit einer Netzwerksteuerungsstation oder andere Aktionen umfassen, die für das Netzwerkmedium geeignet sind.

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

Darüber hinaus sollte ProtocolCmRegisterSap alle erforderlichen Zuordnungen dynamischer Ressourcen und Strukturen ausführen, die der Aufruf-Manager benötigt, um Zustandsinformationen über die SAP im Auftrag des verbindungsorientierten Clients zu verwalten. Zu diesen Ressourcen gehören speicherpuffer, Datenstrukturen, Ereignisse und andere ähnliche Ressourcen. Ein Anruf-Manager muss auch alle Ressourcen initialisieren, die er zugewiesen hat, bevor er die Steuerung an NDIS zurückgibt. Anrufmanager müssen den von NDIS bereitgestellten Handle zur Identifizierung des SAP-Speichers, der bei NdisSapHandle bereitgestellt wird, für die zukünftige Verwendung in ihrem Kontextbereich speichern.

Wenn ProtocolCmRegisterSap NDIS_STATUS_SUCCESS zurückgibt, sollte die Adresse dieses Zustandsbereichs in CallMgrSapContext nach der Zuordnung des SAP-Statusbereichs festgelegt werden, bevor die Steuerung an NDIS zurückgegeben wird. Leiten Sie dazu CallMgrSapContext ab, und speichern Sie einen Zeiger auf den Datenbereich als Wert des Handles. Beispiel:

*CallMgrSapContext = SomeBuffer ;

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

Nachdem ein Anrufmanager eine SAP im Namen eines verbindungsorientierten Clients registriert hat, benachrichtigt er diesen Client über ein eingehendes Anrufangebot, das an diese SAP weitergeleitet wird, indem er aufruft. NdisCmDispatchIncomingCall.

Beispiele

Um eine ProtocolCmRegisterSap-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 ProtocolCmRegisterSap-Funktion mit dem Namen "MyCmRegisterSap" zu definieren, verwenden Sie den typ PROTOCOL_CM_REG_SAP , 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 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_CM_REG_SAP 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 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	Windows
Kopfzeile	ndis.h (einschließlich Ndis.h)
IRQL	<= DISPATCH_LEVEL