PROTOCOL_CO_CREATE_VC Rückruffunktion (ndis.h)

Artikel
02/29/2024

Die ProtocolCoCreateVc-Funktion ist eine erforderliche Funktion, die Ressourcen zuordnet, die für einen Aufruf-Manager oder Client zum Aktivieren und Verwalten einer virtuellen Verbindung (Virtual Connection, VC) erforderlich sind.

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

Syntax

PROTOCOL_CO_CREATE_VC ProtocolCoCreateVc;

NDIS_STATUS ProtocolCoCreateVc(
  [in]  NDIS_HANDLE ProtocolAfContext,
  [in]  NDIS_HANDLE NdisVcHandle,
  [out] PNDIS_HANDLE ProtocolVcContext
)
{...}

Parameter

[in] ProtocolAfContext

Gibt das Handle für einen durch das Protokoll zugeordneten Kontextbereich an, in dem der Aufruf-Manager oder Client seinen geöffneten Zustand beibehält. Der Aufruf-Manager hat dieses Handle über seine ProtocolCmOpenAf-Funktion bereitgestellt. Der Client hat dieses Handle bereitgestellt, wenn er NdisClOpenAddressFamilyEx über seine ProtocolCoAfRegisterNotify-Funktion aufgerufen hat .

[in] NdisVcHandle

Gibt ein von NDIS bereitgestelltes Handle an, das diese virtuelle Verbindung eindeutig identifiziert. Dieses Handle ist für den Protokolltreiber nicht transparent und für die Verwendung der NDIS-Bibliothek reserviert. Der Aufruf-Manager und der Client müssen dieses Handle jedoch speichern, um nachfolgende Aufrufe von NdisCo/Cl/Cm/MCmXxx-Funktionen zu übergeben, die diesen Vc betreffen.

[out] ProtocolVcContext

Gibt das Handle für einen vom Protokoll bereitgestellten Kontextbereich an, in dem der Aufruf-Manager oder Client den Zustand zu dieser virtuellen Verbindung verwaltet.

Rückgabewert

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

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	Gibt an, dass der Anrufmanager oder Client alle erforderlichen Ressourcen erfolgreich zugeordnet und/oder initialisiert hat, die zum Herstellen und Verwalten einer virtuellen Verbindung erforderlich sind.
NDIS_STATUS_RESOURCES	Gibt an, dass der Anruf-Manager oder Client seine Ressourcen zum Herstellen und Verwalten einer virtuellen Verbindung nicht zuordnen und/oder initialisieren konnte.
NDIS_STATUS_XXX	Gibt an, dass der Anruf-Manager oder Client sich selbst nicht in einen Zustand festlegen konnte, in dem eine virtuelle Verbindung hergestellt werden konnte. Dies kann ein Fehlerrückgabewert sein, der von einer anderen NDIS-Bibliotheksroutine weitergegeben wird. Hinweis Anruf-Manager oder Clients können keine NDIS_STATUS_PENDING aus ihren ProtocolCoCreateVc-Funktionen zurückgeben. Wenn Sie ausstehend zurückgeben, wird diese virtuelle Verbindung unbrauchbar, und die NDIS-Bibliothek ruft den Client oder den Anruf-Manager auf, um sie zu löschen.

Hinweise

Die ProtocolCoCreateVc-Funktion eines Aufruf-Managers oder Clients wird immer aufgerufen, wenn der entsprechende Client bzw. Der entsprechende Anruf-Manager NdisCoCreateVc aufruft. Clients initiieren die Erstellung von VCs, indem sie ihre ausgehenden Anrufe einrichten, bevor sie NdisClMakeCall aufrufen. Ein Anrufmanager initiiert die Erstellung eines Nachweises, indem er seinen Client benachrichtigt, dass der CM ein eingehendes Anrufangebot von einem Remoteknoten erhalten hat, der an einen SAP weitergeleitet wird, der bereits von diesem Client bei der CM registriert ist, bevor der CM aufruft. NdisCmDispatchIncomingCall.

ProtocolCoCreateVc führt alle erforderlichen Zuordnungen dynamischer Ressourcen und Strukturen durch, die der Aufruf-Manager oder Client benötigt, um nachfolgende Vorgänge für eine aktivierte Vc auszuführen. Zu diesen Ressourcen gehören unter anderem Speicherpuffer, Datenstrukturen, Ereignisse und ähnliche Ressourcen. Anrufmanager und Clients sollten auch alle relevanten Pro-VC-Strukturen initialisieren, die sie benötigen, wenn ein Anruf eingerichtet wird.

Verbindungsorientierte Protokolltreiber müssen das Handle für den in NdisVcHandle angegebenen Vc in ihrem Pro-VC-Zustandsbereich speichern, um in zukünftigen Vorgängen für diese virtuelle Verbindung verwendet zu werden. Der NdisVcHandle ist als erforderlicher Parameter für NdisCoXxx, NdisCmXxx und/oder NdisClXxx , die ein solches verbindungsorientiertes Protokoll anschließend aufruft.

Wenn ein Aufrufmanager oder Client Arbeitsspeicher für seine eigenen Pro-VC-Daten zugewiesen und deren Zustand initialisiert hat, sollte die Adresse dieser Datenstruktur im Handle festgelegt werden, bevor die Steuerung an NDIS zurückgegeben wird. Zu diesem Zweck dereferenzieren Sie das Handle, und speichern Sie einen Zeiger auf den protokollseitig zugeordneten Datenbereich als Wert des Handles. Beispiel:

*ProtocolVcContext = SomeBuffer;

Wenn ProtocolCoCreateVc die Ressource, die für nachfolgende E/A-Vorgänge im Netzwerk benötigt wird, nicht zuordnen kann, sollte es alle Ressourcen freigeben, die für diese Vc zugewiesen wurden, und die Steuerung mit einer status NDIS_STATUS_RESOURCES zurückgeben.

Wenn ProtocolCoCreateVc die erforderlichen Vorgänge abgeschlossen hat und den Anruf-Manager oder Client bereit gemacht hat, die Aufrufinitialisierung für diese virtuelle Verbindung durchzuführen, sollte ProtocolCoCreateVc die Steuerung so schnell wie möglich mit einer status NDIS_STATUS_SUCCESS zurückgeben.

Aufrufe von ProtocolCoCreateVc sind grundsätzlich synchron. Das heißt, ProtocolCoCreateVckann keine NDIS_STATUS_PENDING zurückgeben.

Nachdem die ProtocolCoCreateVc-Funktion eines Aufrufmanagers die Steuerung zurückgegeben hat, wird die ProtocolCmMakeCall-Funktion des Aufruf-Managers aufgerufen, um eine Verbindung mit einem Remoteknoten herzustellen. Anruf-Manager sollten keine Aktion in ProtocolCmMakeCall ergreifen, die tatsächlich einen Aufruf erstellt, da es möglich ist, dass der Vc zerstört wird, bevor ein Aufruf aufgrund einer Fehlerbedingung in einer anderen Komponente der verbindungsorientierten NDIS eingerichtet wird.

Nachdem die ProtocolCoCreateVc-Funktion eines Clients die Steuerung zurückgegeben hat, wird die ProtocolClIncomingCall-Funktion des Clients benachrichtigt, wenn eine remote initiierte Anforderung zum Herstellen einer Verbindung mit einem zuvor vom Client registrierten SAP über das Netzwerk eingeht.

Beispiele

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

PROTOCOL_CO_CREATE_VC MyCoCreateVc;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyCoCreateVc(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  NdisVcHandle,
    PNDIS_HANDLE  ProtocolVcContext
    )
  {...}

Der PROTOCOL_CO_CREATE_VC 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_CO_CREATE_VC 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 ProtocolCoCreateVc (NDIS 5.1)) in Windows Vista. Unterstützt für NDIS 5.1-Treiber (siehe ProtocolCoCreateVc (NDIS 5.1)) in Windows XP.
Zielplattform	Windows
Kopfzeile	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL