PROTOCOL_CM_MAKE_CALL Rückruffunktion (ndis.h)
Die ProtocolCmMakeCall-Funktion ist eine erforderliche Funktion, die medienspezifische Parameter für eine virtuelle Verbindung (VC) einrichtet und die virtuelle Verbindung aktiviert.
Syntax
PROTOCOL_CM_MAKE_CALL ProtocolCmMakeCall;
NDIS_STATUS ProtocolCmMakeCall(
[in] NDIS_HANDLE CallMgrVcContext,
[in, out] PCO_CALL_PARAMETERS CallParameters,
[in, optional] NDIS_HANDLE NdisPartyHandle,
[out, optional] PNDIS_HANDLE CallMgrPartyContext
)
{...}
Parameter
[in] CallMgrVcContext
Gibt das Handle für einen vom Anruf-Manager zugeordneten Kontextbereich an, in dem die Anruf-Manager ihren Status pro Vc beibehalten. Der Aufruf-Manager hat dieses Handle über seine ProtocolCoCreateVc-Funktion für NDIS bereitgestellt.
[in, out] CallParameters
Zeiger auf eine CO_CALL_PARAMETERS Struktur, die die parameter enthält, die von einem verbindungsorientierten Client für diesen ausgehenden Aufruf angegeben werden.
[in, optional] NdisPartyHandle
Gibt ein Handle an, das von NDIS bereitgestellt wird und die erste Seite der virtuellen Multipointverbindung eindeutig identifiziert. Dieses Handle ist für den Anruf-Manager undurchsichtig und für die Verwendung der NDIS-Bibliothek reserviert. Dieses Handle ist NULL , wenn der Client keinen ausgehenden Mehrpunktaufruf ein richtet.
[out, optional] CallMgrPartyContext
Gibt bei der Rückgabe ein Handle für einen vom Anruf-Manager bereitgestellten Kontextbereich an, in dem der Anruf-Manager den Zustand über die erste Partei des Multipoint-Anrufs verwaltet. Wenn NdisPartyHandleNULL ist, muss dieses Handle auf NULL festgelegt werden.
Rückgabewert
ProtocolCmMakeCall gibt den status seiner Vorgänge als einen der folgenden Werte zurück:
| Rückgabecode | Beschreibung |
|---|---|
|
Gibt an, dass der Anruf-Manager die für den Anruf erforderlichen Ressourcen erfolgreich zugeordnet hat und die virtuelle Verbindung mit dem Miniporttreiber aktivieren konnte. |
|
Gibt an, dass der Anruf-Manager die Anforderung zum asynchronen Ausführen eines Aufrufs abschließt. Wenn der Anrufmanager alle Vorgänge für das Tätigen eines Anrufs abgeschlossen hat, muss er NdisCmMakeCallComplete aufrufen, um NDIS zu signalisieren, dass dieser Anruf abgeschlossen wurde. |
|
Gibt an, dass der Anruf-Manager seine Ressourcen nicht zuordnen und/oder initialisieren konnte, um die virtuelle Verbindung zu aktivieren, wie vom Client angefordert. |
|
Gibt an, dass der Aufruf-Manager eine virtuelle Verbindung nicht aktivieren konnte, weil der Aufrufer ungültige oder nicht verfügbare Features in den Aufrufparametern angefordert hat, die unter CallParameters angegeben sind. |
Hinweise
Wenn ProtocolCmMakeCall eine explizite NdisPartyHandle erhält, wurde diese VC vom Client für einen Multipoint-Aufruf erstellt. Der Anruf-Manager muss alle erforderlichen Ressourcen zuordnen und initialisieren, die zum Verwalten von Zustandsinformationen und zur Steuerung eines Mehrpunktaufrufs erforderlich sind. Zu diesen Ressourcen gehören unter anderem Speicherpuffer, Datenstrukturen, Ereignisse und ähnliche Ressourcen. Wenn der Anruf-Manager die erforderlichen Ressourcen für seine Zustandsbereiche nicht zuordnen oder initialisieren kann, sollte er die Steuerung mit NDIS_STATUS_RESOURCES an NDIS zurückgeben.
ProtocolCmMakeCall kommuniziert bei Bedarf mit Netzwerksteuerungsgeräten oder anderen medienspezifischen Akteuren, um eine Verbindung zwischen dem lokalen Knoten und einem Remoteknoten basierend auf den unter CallParameters angegebenen Aufrufparametern herzustellen. Zu diesen Aktionen können unter anderem die Kommunikation mit der Schalthardware, die Kommunikation mit einer Netzwerkkontrollstation oder andere aktionen für das Netzwerkmedium gehören.
Wenn ein Anrufmanager für die Kommunikation mit Netzwerkhardware (z. B. einem Netzwerkswitch) erforderlich ist, sollte er eine virtuelle Verbindung mit dem Netzwerksteuerungsgerät verwenden, das er in seiner ProtocolBindAdapterEx-Funktion eingerichtet hat. Anrufmanager kommunizieren mit ihrer Netzwerkhardware über den Miniporttreiber, indem sie NdisCoSendNetBufferLists aufrufen. Miniport-Treiber mit integrierter Unterstützung für die Anrufverwaltung rufen nicht NdisCoSendNetBufferLists auf, sondern übertragen die Daten selbst.
Nachdem ein Anrufmanager alle erforderlichen Kommunikationen mit seiner Netzwerkhardware durchgeführt hat, die für sein Medium erforderlich ist, müssen Anrufmanager NdisCmActivateVc aufrufen.
Wenn es sich bei diesem Aufruf um einen Mehrpunktaufruf handelte, sollte die Adresse des Zustandsblocks im Handle CallMgrPartyContext festgelegt werden, bevor die Steuerung an NDIS zurückgegeben wird, nachdem der Anruf-Manager mit der Netzwerkhardware kommuniziert, die Anrufparameter überprüft und die zugehörigen Statusdaten zugeordnet und initialisiert hat. Das Handle wird festgelegt, indem das Handle dereferenziert und ein Zeiger auf den Zustandsblock als Wert des Handles gespeichert wird. Beispiel:
*CallMgrPartyContext = SomeBuffer ;
Wenn ProtocolCmMakeCall die erforderlichen Vorgänge für sein Netzwerk abgeschlossen hat und die Vc erfolgreich über NdisCmActivateVc aktiviert wurde, sollte ProtocolCmMakeCall die Steuerung so schnell wie möglich mit einem status STATUS_SUCCESS zurückgeben.
Nachdem ProtocolCmMakeCall die Steuerung an NDIS zurückgegeben hat, sollte der Anruf-Manager erwarten, dass er keine weiteren Aktionen für diesen Aufruf ergreifen wird, um ihn einzurichten. ProtocolCmMakeCall ist für das Herstellen der Verbindung verantwortlich, damit der Client Datenübertragungen über das Netzwerk auf dieser Vc durchführen kann. Der Anruf-Manager kann jedoch später aufgerufen werden, um die Dienstqualität des Anrufs zu ändern, Parteien hinzuzufügen oder zu löschen, wenn es sich um eine Multipoint-VC handelt, und schließlich, um diesen Anruf zu beenden.
Beispiele
Um eine ProtocolCmMakeCall-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten 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 ProtocolCmMakeCall-Funktion mit dem Namen "MyCmMakeCall" zu definieren, verwenden Sie den typ PROTOCOL_CM_MAKE_CALL , wie in diesem Codebeispiel gezeigt:
PROTOCOL_CM_MAKE_CALL MyCmMakeCall;
Implementieren Sie dann Ihre Funktion wie folgt:
_Use_decl_annotations_
NDIS_STATUS
MyCmMakeCall(
NDIS_HANDLE CallMgrVcContext,
PCO_CALL_PARAMETERS CallParameters,
NDIS_HANDLE NdisPartyHandle,
PNDIS_HANDLE CallMgrPartyContext
)
{...}
Der PROTOCOL_CM_MAKE_CALL 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_CM_MAKE_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 ProtocolCmMakeCall (NDIS 5.1)) in Windows Vista. Unterstützt für NDIS 5.1-Treiber (siehe ProtocolCmMakeCall (NDIS 5.1)) in Windows XP. |
| Zielplattform | Windows |
| Kopfzeile | ndis.h (include Ndis.h) |
| IRQL | <= DISPATCH_LEVEL |