PROTOCOL_CM_CLOSE_CALL Rückruffunktion (ndis.h)

Artikel
02/27/2024

Die ProtocolCmCloseCall-Funktion ist eine erforderliche Funktion, die einen vorhandenen Aufruf beendet und alle Ressourcen freigibt, die der Aufruf-Manager für den Aufruf zugewiesen hat.

Hinweis Sie müssen die Funktion mit dem typ PROTOCOL_CM_CLOSE_CALL deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

PROTOCOL_CM_CLOSE_CALL ProtocolCmCloseCall;

NDIS_STATUS ProtocolCmCloseCall(
  [in]           NDIS_HANDLE CallMgrVcContext,
  [in, optional] NDIS_HANDLE CallMgrPartyContext,
  [in, optional] PVOID CloseData,
  [in, optional] UINT Size
)
{...}

Parameter

[in] CallMgrVcContext

Gibt das Handle für einen vom Anruf-Manager zugeordneten Kontextbereich an, in dem der Anruf-Manager seinen Status pro Vc verwaltet. Dieses Handle wurde NDIS von der Protokoll-Manager-Funktion ProtocolCmMakeCall bereitgestellt.

[in, optional] CallMgrPartyContext

Gibt ggf. das Handle für einen vom Anruf-Manager zugewiesenen Kontextbereich an, in dem der Anrufmanager Informationen zu einer Partei auf einem Multipoint-Vc verwaltet. Dieses Handle ist NULL , wenn der geschlossene Aufruf kein Mehrpunktaufruf ist.

[in, optional] CloseData

Zeiger auf einen Puffer mit verbindungsorientierten clientspezifischen Daten, die über die Verbindung gesendet werden sollen, bevor der Aufruf beendet wird. Dieser Parameter ist NULL , wenn das zugrunde liegende Netzwerkmedium beim Schließen einer Verbindung keine Datenübertragungen unterstützt.

[in, optional] Size

Gibt die Länge des Puffers bei CloseData in Byte an, null, wenn CloseDataNULL ist.

Rückgabewert

ProtocolCmCloseCall gibt den status seiner Vorgänge als einen der folgenden zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	Gibt an, dass der Anruf-Manager den Anruf erfolgreich beendet hat.
NDIS_STATUS_PENDING	Gibt an, dass der Anruf-Manager die Anforderung zum asynchronen Beenden des Aufrufs abschließt. Wenn der Anrufmanager alle Vorgänge abgeschlossen hat, die zum Beenden der Verbindung erforderlich sind, muss er NdisCmCloseCallComplete aufrufen, um NDIS zu signalisieren, dass der Anruf geschlossen wurde.
NDIS_STATUS_INVALID_DATA	Gibt an, dass CloseData angegeben wurde, aber das zugrunde liegende Netzwerkmedium das gleichzeitige Senden von Daten mit dem Beenden eines Anrufs nicht unterstützt.
NDIS_STATUS_XXX	Gibt an, dass der Anruf-Manager den Anruf nicht beenden konnte. Der tatsächlich zurückgegebene Fehler kann ein status sein, der von einer anderen NDIS-Bibliotheksroutine weitergegeben wird.

Hinweise

ProtocolCmCloseCall kommuniziert mit Netzwerksteuerungsgeräten oder anderen medienspezifischen Akteuren, wie von ihren Medien erforderlich, um eine Verbindung zwischen dem lokalen Knoten und einem Remoteknoten zu beenden. Wenn der Anruf-Manager mit Netzwerksteuerungsgeräten (z. B. einem Netzwerkswitch) kommunizieren muss, sollte er eine virtuelle Verbindung mit dem Netzwerksteuerungsgerät verwenden, das er in seiner ProtocolBindAdapterEx-Funktion eingerichtet hat. Eigenständige Anrufmanager kommunizieren mit solchen Netzwerkgeräten, indem sie NdisCoSendNetBufferLists aufrufen. Miniport-Treiber mit integrierter Unterstützung für die Anrufverwaltung rufen nie NdisCoSendNetBufferLists auf. Stattdessen übertragen sie die Daten direkt über das Netzwerk.

Wenn CloseData nicht NULL ist und das Senden von Daten beim Beenden der Verbindung von den Medien unterstützt wird, die dieser Aufruf-Manager verarbeitet, sollte der Anruf-Manager die unter CloseData angegebenen Daten an den Remoteknoten übertragen, bevor die Anrufbeendigung abgeschlossen wird. Wenn das gleichzeitige Senden von Daten mit einer beendeten Verbindung nicht unterstützt wird, sollten Anruf-Manager NDIS_STATUS_INVALID_DATA zurückgeben.

Wenn ProtocolCmCloseCall einen expliziten CallMgrPartyContext übergeben wird, handelt es sich bei dem beendeten Aufruf um eine Multipoint-VC, und der Anruf-Manager muss die erforderliche Netzwerkkommunikation mit seiner Netzwerkhardware durchführen, je nach Medientyp, um den Anruf als Mehrpunktanruf zu beenden. Der Anruf-Manager muss auch den zuvor zugewiesenen Arbeitsspeicher in ProtocolCmMakeCall für den von CallMgrPartyContext angegebenen Status pro Partei freigeben. Wenn diese Ressourcen nicht ordnungsgemäß freigegeben, aufgehoben oder anderweitig deaktiviert werden, entsteht ein Speicherverlust.

Nachdem der Anruf mit dem Netzwerk beendet wurde, alle schließenden Daten gesendet und alle Ressourcen bei CallMgrPartyContext freigegeben wurden, muss der Anrufmanager NdisCmDeactivateVc aufrufen. Dadurch werden NDIS und den zugrunde liegenden Miniporttreiber benachrichtigt, sofern vorhanden, dass keine weiteren Übertragungen auf den angegebenen Vc zu erwarten sind.

Beispiele

Um eine ProtocolCmCloseCall-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der funktion identifiziert, die Sie definieren. Windows bietet eine Reihe von Funktionstypen für Treiber. 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 Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine ProtocolCmCloseCall-Funktion mit dem Namen "MyCmCloseCall" zu definieren, verwenden Sie den typ PROTOCOL_CM_CLOSE_CALL , wie in diesem Codebeispiel gezeigt:

PROTOCOL_CM_CLOSE_CALL MyCmCloseCall;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyCmCloseCall(
    NDIS_HANDLE  CallMgrVcContext,
    NDIS_HANDLE  CallMgrPartyContext,
    PVOID  CloseData,
    UINT  Size
    )
  {...}

Der PROTOCOL_CM_CLOSE_CALL Funktionstyp ist in der Ndis.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, müssen Sie der Funktionsdefinition die anmerkung Use_decl_annotations hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den PROTOCOL_CM_CLOSE_CALL 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 ProtocolCmCloseCall (NDIS 5.1)) in Windows Vista. Unterstützt für NDIS 5.1-Treiber (siehe ProtocolCmCloseCall (NDIS 5.1)) in Windows XP.
Zielplattform	Windows
Kopfzeile	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL