PROTOCOL_CL_ADD_PARTY_COMPLETE Rückruffunktion (ndis.h)

Artikel
03/05/2024

Die ProtocolClAddPartyComplete-Funktion ist für verbindungsorientierte NDIS-Clients erforderlich, die Multipointverbindungen einrichten. Solche Clients müssen über ProtocolClAddPartyComplete-Funktionen verfügen, um die asynchronen Vorgänge abzuschließen, die sie mit NdisClAddParty initiieren. Andernfalls kann die vom Protokolltreiber registrierte ProtocolClAddPartyComplete-Funktion einfach die Steuerung zurückgeben.

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

Syntax

PROTOCOL_CL_ADD_PARTY_COMPLETE ProtocolClAddPartyComplete;

void ProtocolClAddPartyComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolPartyContext,
  [in] NDIS_HANDLE NdisPartyHandle,
  [in] PCO_CALL_PARAMETERS CallParameters
)
{...}

Parameter

[in] Status

Gibt die endgültige status des vom Client initiierten Add-Party-Vorgangs an. Dies kann eine der folgenden Sein:

NDIS_STATUS_SUCCESS

Die angegebene Partei wurde der aktiven Multipoint-VC des Clients hinzugefügt.

NDIS_STATUS_RESOURCES

NDIS konnte nicht genügend Ressourcen zuweisen, um die neue Partei nachzuverfolgen.

NDIS_STATUS_FAILURE

Der Client hat ein ungültiges NdisVcHandle an NdisClAddParty übergeben.

NDIS_STATUS_XXX

Die ProtocolCmAddParty-Funktion des Aufruf-Managers hat einen CM-bestimmten Wert zurückgegeben, um anzugeben, warum die Partei nicht zur Vc hinzugefügt werden konnte.

[in] ProtocolPartyContext

Gibt das vom Client bereitgestellte Handle an, das ursprünglich an NdisClAddParty übergeben wurde.

[in] NdisPartyHandle

Wenn Status NDIS_STATUS_SUCCESS ist, stellt dieses von NDIS bereitgestellte Handle die Zuordnung zwischen dem Anrufmanager und dem Client in Bezug auf diese Partei dar. Andernfalls ist der Versuch, eine Partei hinzuzufügen, fehlgeschlagen, und der Client sollte diesen Parameter als ungültiges Handle betrachten.

[in] CallParameters

Zeiger auf eine Struktur vom Typ CO_CALL_PARAMETERS, die ursprünglich vom Client für den Aufruf von NdisClAddParty eingerichtet, aber möglicherweise später vom Anrufmanager geändert wurde.

Rückgabewert

Keine

Bemerkungen

Ein Aufruf von ProtocolClAddPartyComplete gibt den Abschluss des asynchronen Vorgangs an, der initiiert wurde, wenn der Client NdisClAddParty aufgerufen hat. Wenn der Eingabestatus auf einen anderen Wert als NDIS_STATUS_SUCCESS festgelegt ist, kann ProtocolClAddPartyComplete die vom Client zugewiesenen Puffer unter ProtocolPartyContext und CallParameters freigeben oder wiederverwenden.

Wenn der Versuch, eine Partei hinzuzufügen, erfolgreich war, sollte ProtocolClAddPartyComplete die Eingabe NdisPartyHandle für nachfolgende Aufrufe von NDIS-Bibliotheksfunktionen für diese Partei im Bereich ProtocolPartyContext des Clients speichern. Beispielsweise muss der Client dieses Handle in einem nachfolgenden Aufruf von NdisClDropParty schließlich übergeben, es sei denn, die Remotepartei, die er darstellt, schließt zuerst ihre Verbindung.

Die Struktur bei CallParameters wurde ursprünglich vom Client zugeordnet und initialisiert, der diesen Zeiger an übergeben hat.
NdisClAddParty. Der Anruf-Manager hat jedoch möglicherweise die vom Client bereitgestellten Werte geändert, um die Ergebnisse der Cm-Aushandlung mit dem Netzwerk oder mit einem Signalpeer während der Verarbeitung der Add-Party-Anforderung des Clients widerzuspiegeln. Um zu bestimmen, ob der Aufruf-Manager Änderungen vorgenommen hat, kann ProtocolClAddPartyComplete den Flags-Member dieser Struktur überprüfen, ob CALL_PARAMETERS_CHANGED festgelegt ist. Wenn dies der Fall ist, muss ProtocolClAddPartyComplete den Parteistatus aktualisieren, den der Client für diesen Aufruf unter ProtocolPartyContext verwaltet, es sei denn, er findet die Änderungen des CM inakzeptabel. Das jeweilige Signalisierungsprotokoll bestimmt, was der Client in diesem Fall tun kann. Normalerweise ruft ein Client NdisClDropParty auf, wenn er die durch CM geänderten Aufrufparameter für nicht akzeptabel hält.

Abhängig vom Signalisierungsprotokoll des Anruf-Managers können die Datenverkehrsparameter bei CallParameters für alle Parteien bei einer bestimmten Mehrpunktverbindung identisch sein. Das heißt, da der Client eines solchen Anruf-Managers Parteien zu einer Mehrpunktverbindung hinzufügt, die der Client ursprünglich mit NdisClMakeCall eingerichtet hat, kann er nur die Zieladresse jeder Partei angeben und die Datenverkehrsparameter bei jedem Aufruf von NdisClAddParty wie ursprünglich für die Multipoint-VC eingerichtet lassen.

Beispiele

Um eine ProtocolClAddPartyComplete-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der zu definierenden Funktion identifiziert. 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 ProtocolClAddPartyComplete-Funktion mit dem Namen "MyClAddPartyComplete" zu definieren, verwenden Sie den typ PROTOCOL_CL_ADD_PARTY_COMPLETE , wie in diesem Codebeispiel gezeigt:

PROTOCOL_CL_ADD_PARTY_COMPLETE MyClAddPartyComplete;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
VOID
 MyClAddPartyComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolPartyContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

Der PROTOCOL_CL_ADD_PARTY_COMPLETE Funktionstyp ist in der Headerdatei Ndis.h 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_CL_ADD_PARTY_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 ProtocolClAddPartyComplete (NDIS 5.1)) in Windows Vista. Unterstützt für NDIS 5.1-Treiber (siehe ProtocolClAddPartyComplete (NDIS 5.1)) in Windows XP.
Zielplattform	Windows
Kopfzeile	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL