PROTOCOL_CL_MAKE_CALL_COMPLETE Rückruffunktion (ndis.h)

Artikel
08/07/2023

Die ProtocolClMakeCallComplete-Funktion wird von verbindungsorientierten NDIS-Clients verwendet, die ausgehende Aufrufe tätigen. Solche Clients müssen über ProtocolClMakeCallComplete-Funktionen verfügen, um die asynchronen Vorgänge abzuschließen, die sie mit NdisClMakeCall initiieren. Andernfalls kann die registrierte ProtocolClMakeCallComplete-Funktion eines solchen Protokolltreibers einfach die Steuerung zurückgeben.

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

Syntax

PROTOCOL_CL_MAKE_CALL_COMPLETE ProtocolClMakeCallComplete;

void ProtocolClMakeCallComplete(
  [in]           NDIS_STATUS Status,
  [in]           NDIS_HANDLE ProtocolVcContext,
  [in, optional] NDIS_HANDLE NdisPartyHandle,
  [in]           PCO_CALL_PARAMETERS CallParameters
)
{...}

Parameter

[in] Status

Gibt den endgültigen status des ursprünglichen Aufrufs des Clients an NdisClMakeCall an, der einer der folgenden Sein kann:

NDIS_STATUS_SUCCESS

Der Versuch des Clients, eine virtuelle Verbindung einzurichten, war erfolgreich. Folglich kann der Client mit übertragungen auf der aktiven VC fortfahren, indem er das von NdisCoCreateVc zurückgegebene NdisVcHandle verwendet, das der Client in seinem Pro-VC-Kontextbereich unter ProtocolVcContext gespeichert hat.

NDIS_STATUS_RESOURCES

NDIS, der Anruf-Manager oder ein zugrunde liegender Treiber konnten nicht genügend Ressourcen zuweisen, um die Verbindung einzurichten.

NDIS_STATUS_XXX

Der Anruf-Manager oder der zugrunde liegende Miniporttreiber konnte keine aktive Verbindung herstellen, und NDIS hat diesen treiberbedingten Fehler status an den Client weitergegeben.

[in] ProtocolVcContext

Gibt das Handle für den Pro-VC-Kontextbereich des Clients an, den der Client ursprünglich für NDIS bereitgestellt hat, als er NdisCoCreateVc aufgerufen hat, um die VC für den ausgehenden Aufruf einzurichten.

[in, optional] NdisPartyHandle

Wenn Status NDIS_STATUS_SUCCESS ist und der Client eine Mehrpunkt-VC erstellt hat, indem er ein explizites ProtocolPartyContext-Handle an NdisClMakeCall übergeben hat, ist dies ein gültiges NdisPartyHandle . Andernfalls ist dieser Parameter NULL.

ProtocolClMakeCallComplete muss alle gültigen Eingaben NdisPartyHandle speichern, in der Regel im kontextspezifischen Kontextbereich des Clients. Der Client muss dieses Handle verwenden, wenn (oder wann) er einen nachfolgenden Aufruf von NdisClDropParty oder NdisClCloseCall ausgibt, der auf diese Partei verweist.

[in] CallParameters

Zeiger auf eine gepufferte CO_CALL_PARAMETERS-Struktur. Der Client hat diesen Puffer zugewiesen und diese Struktur mit vom Client bestimmten Daten initialisiert, bevor er diesen Zeiger an NdisClMakeCall übergibt. Während der Verarbeitung der Clientanforderung kann der Anruf-Manager diese Daten so ändern, dass sie die Ergebnisse der Aushandlung mit dem Netzwerk oder einem Signal peer widerspiegeln.

Rückgabewert

Keine

Bemerkungen

Ein Aufruf von ProtocolClMakeCallComplete gibt an, dass der Anruf-Manager die Verarbeitung der Clientanforderung zum Herstellen einer virtuellen Verbindung mit NdisClMakeCall abgeschlossen hat.

Wenn der Versuch des Clients, einen ausgehenden Aufruf einzurichten, nicht erfolgreich ist (der Eingabestatus ist nichts anderes als NDIS_STATUS_SUCCESS), sollte ProtocolClMakeCallComplete die folgenden Schritte ausführen:

Freigeben oder Vorbereiten der Wiederverwendung des Bereichs ProtocolPartyContext (falls vorhanden) und des Puffers bei CallParameters , den der Client zugewiesen hat.
Beenden Sie die vom Client erstellte VC mit einem Aufruf von NdisCoDeleteVc , und lassen Sie den clientseitig zugewiesenen Bereich ProtocolVcContext frei, oder bereiten Sie die Wiederverwendung vor.

Andernfalls sollte ProtocolClMakeCallComplete die folgenden Schritte ausführen:

Überprüfen Sie das Flags-Element der Struktur unter CallParameters , um festzustellen, ob CALL_PARAMETERS_CHANGED festgelegt ist. Dies bedeutet, dass der Aufruf-Manager die vom Client bereitgestellten Aufrufparameter geändert hat.
Wenn ja, überprüfen Sie die Daten unter CallParameters , um zu ermitteln, ob sie für diese Verbindung akzeptabel sind.
Beispielsweise kann der Client die gepufferten Aufrufparameter für die aktive VC beibehalten, das NdisPartyHandle speichern, wenn es sich um eine Multipoint-VC handelt, und den Client im Allgemeinen für nachfolgende Übertragungen und andere Vorgänge auf der aktiven VC bereit machen, wenn er die angegebenen Aufrufparameter für zufriedenstellend hält.
Andernfalls bestimmt das Signalisierungsprotokoll, ob der Client versuchen kann, um akzeptable Anrufparameter mit dem Anruf-Manager neu zu verhandeln.
Beispielsweise kann ein bestimmter Anruf-Manager seinen Clients erlauben, NdisClModifyCallQoS unter diesen Umständen ein oder mehrere Male aufzurufen.
Wenn die vom CM geänderten Aufrufparameter inakzeptabel sind und eine weitere Neuverhandlung nicht möglich ist, muss ProtocolClMakeCallComplete den Aufruf mit NdisClCloseCall abreißen.
In diesem Fall sollte ProtocolClMakeCallCompletenicht versuchen, clientseitig zugewiesene Ressourcen bei der Rückgabe von NdisClCloseCall freizugeben, sondern kann einfach die Steuerung zurückgeben. Stattdessen sollte der Client die zugewiesenen Ressourcen freigeben (oder sie für die Wiederverwendung vorbereiten) in seiner ProtocolClCloseCallComplete-Funktion .

Beispiele

Um eine ProtocolClMakeCallComplete-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 ProtocolClMakeCallComplete-Funktion mit dem Namen "MyClMakeCallComplete" zu definieren, verwenden Sie den PROTOCOL_CL_MAKE_CALL_COMPLETE-Typ , wie in diesem Codebeispiel gezeigt:

PROTOCOL_CL_MAKE_CALL_COMPLETE MyClMakeCallComplete;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
VOID
 MyClMakeCallComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

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