PROTOCOL_CL_REGISTER_SAP_COMPLETE Rückruffunktion (ndis.h)

Artikel
08/07/2023

Ein verbindungsorientierter NDIS-Client, der eingehende Aufrufe akzeptiert, muss über eine ProtocolClRegisterSapComplete-Funktion verfügen, um die asynchronen Vorgänge abzuschließen, die er mit NdisClRegisterSap initiiert. Andernfalls kann die registrierte ProtocolClRegisterSapComplete-Funktion eines solchen Protokolltreibers einfach die Steuerung zurückgeben.

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

Syntax

PROTOCOL_CL_REGISTER_SAP_COMPLETE ProtocolClRegisterSapComplete;

void ProtocolClRegisterSapComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolSapContext,
  [in] PCO_SAP Sap,
  [in] NDIS_HANDLE NdisSapHandle
)
{...}

Parameter

[in] Status

Gibt den endgültigen status des Aufrufs von NdisClRegisterSap durch den Client an, der einer der folgenden Sein kann:

NDIS_STATUS_SUCCESS

Die SAP wurde sowohl bei NDIS als auch beim Anruf-Manager registriert, der anschließend aufruft NdisCmDispatchIncomingCall , wenn es ein eingehendes Anrufangebot empfängt, das an den angegebenen SAP gerichtet ist, wodurch NDIS den Client aufruft ProtocolClIncomingCall-Funktion .

NDIS_STATUS_RESOURCES

NDIS oder der Anrufmanager konnte keine erforderlichen Ressourcen zuordnen und/oder initialisieren, um sap zu registrieren und zu verwalten.

NDIS_STATUS_INVALID_DATA

Der Client hat eine ungültige Spezifikation bei Sap an NDIS bereitgestellt, die er zur Überprüfung an die ProtocolCmRegisterSap-Funktion des Aufrufmanagers weitergeleitet hat.

NDIS_STATUS_XXX

Beim Versuch, die angegebene SAP-Instanz zu registrieren, ist beim Anruf-Manager ein Fehler aufgetreten, und NDIS hat diesen cm-ermittelten Fehler status an den Client weitergegeben.

[in] ProtocolSapContext

Gibt das Handle für den pro SAP-Kontextbereich des Clients an, den der Client ursprünglich für NDIS bereitgestellt hat, als er NdisClRegisterSap aufgerufen hat. Wenn die Registrierung erfolgreich ist, behält NDIS dieses Kontexthandle bei und verwendet es anschließend in Aufrufen der ProtocolClIncomingCall-Funktion des Clients, die sich auf diese SAP bezieht.

[in] Sap

Zeiger auf den vom Client zugewiesenen Puffer, der die Spezifikation für die zu öffnende SAP enthält. Der Client hat diesen Zeiger ursprünglich an NdisClRegisterSap übergeben.

[in] NdisSapHandle

Wenn Status NDIS_STATUS_SUCCESS ist, gibt ein von NDIS bereitgestelltes gültiges Handle für diese registrierte SAP an, effektiv eine Zuordnung mit NDIS zwischen dem Client und einem bestimmten Anruf-Manager für die vom Client angegebene SAP. Andernfalls ist dieser Parameter NULL. Der Client muss ein gültiges Handle speichern, vorzugsweise im Bereich ProtocolSapContext , für einen eventuellen Aufruf von NdisClDeregisterSap.

Rückgabewert

Keine

Bemerkungen

NDIS ruft ProtocolClRegisterSapComplete auf, um anzugeben, dass der vorherige Aufruf von NdisClRegisterSap des Clients von NDIS und, wenn NDIS den Aufruf nicht erfolgreich ausgeführt hat, vom Anruf-Manager verarbeitet wurde, mit dem der Client die NdisAfHandle-Instanz teilt, die er an NdisClRegisterSap übergeben hat.

Um eingehende Anrufe über eine verbindungsorientierte NIC zu empfangen, ist ein Client ProtocolCoAfRegisterNotify oder Die ProtocolClOpenAfCompleteEx-Funktion registriert in der Regel einen oder mehrere SAPs beim Anruf-Manager.

Um jede SAP zu registrieren, ruft der Client NdisClRegisterSap auf und übergibt das NdisAfHandle , das den Anruf-Manager identifiziert, von dem der Client Benachrichtigungen über eingehende Anrufe erhalten möchte, und NDIS gibt dem Client eine NdisSapHandle an die registrierte SAP zurück, wenn der Aufruf des Clients bei NdisClRegisterSap erfolgreich ist. ProtocolClRegisterSapComplete muss jedes gültige NdisSapHandle speichern, normalerweise im Pro-SAP-ProtokollSapContext-Bereich des Clients, damit sap später mit NdisClDeregisterSap freigegeben werden kann.

Das Format einer SAP ist für den Anruf-Manager spezifisch. Wenn der Anruf-Manager die SAP nicht erkennt, dass der Client versucht, sich zu registrieren, oder wenn die angegebene SAP bereits verwendet wird, kann der Anrufmanager die SAP-Registrierung fehlschlagen. ProtocolClRegisterSapComplete sollte den Eingabestatus auf NDIS_STATUS_SUCCESS überprüfen, bevor sie weitere Schritte ausführen. Wenn beim Versuch, die SAP-Datei zu registrieren, ein Fehler aufgetreten ist,
ProtocolClRegisterSapComplete kann entweder den sapspezifischen Kontextbereich und den Puffer bei Sap freigeben, den der Client zugewiesen hat, oder sie für die Wiederverwendung in einem anderen Aufruf von NdisClRegisterSap vorbereiten.

Ein Client kann eingehende Aufrufe für eine SAP empfangen, auch wenn die SAP-Registrierung noch aussteht, d. h. bevor seine ProtocolClRegisterSapComplete-Funktion aufgerufen wird.

Beispiele

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

PROTOCOL_CL_REGISTER_SAP_COMPLETE MyClRegisterSapComplete;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
VOID
 MyClRegisterSapComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolSapContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle
    )
  {...}

Der PROTOCOL_CL_REGISTER_SAP_COMPLETE Funktionstyp wird 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_REGISTER_SAP_COMPLETE 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 ProtocolClRegisterSapComplete (NDIS 5.1)) in Windows Vista. Unterstützt für NDIS 5.1-Treiber (siehe ProtocolClRegisterSapComplete (NDIS 5.1)) in Windows XP.
Zielplattform	Windows
Kopfzeile	ndis.h (einschließlich Ndis.h)
IRQL	<= DISPATCH_LEVEL