PROTOCOL_CO_OID_REQUEST_COMPLETE Rückruffunktion (ndis.h)

Artikel
08/07/2023

Die ProtocolCoOidRequestComplete-Funktion schließt die Verarbeitung einer asynchronen CoNDIS-OID-Anforderung ab.

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

Syntax

PROTOCOL_CO_OID_REQUEST_COMPLETE ProtocolCoOidRequestComplete;

void ProtocolCoOidRequestComplete(
  [in]      NDIS_HANDLE ProtocolAfContext,
  [in]      NDIS_HANDLE ProtocolVcContext,
  [in]      NDIS_HANDLE ProtocolPartyContext,
  [in, out] PNDIS_OID_REQUEST OidRequest,
  [in]      NDIS_STATUS Status
)
{...}

Parameter

[in] ProtocolAfContext

Ein Handle, das einen Adressfamilienkontextbereich (AF) identifiziert. Wenn es sich bei dem Treiber um einen Client handelt, hat er dieses Handle bereitgestellt, wenn er die NdisClOpenAddressFamilyEx-Funktion , um sich mit dem Anruf-Manager zu verbinden. Wenn der Treiber ein Anruf-Manager oder miniport Call Manager (MCM) ist, hat er dieses Handle über seine ProtocolCmOpenAf-Funktion bereitgestellt.

[in] ProtocolVcContext

Ein Handle, das die aktive virtuelle Verbindung (Active Virtual Connection, VC) identifiziert, für die der Treiber Informationen angefordert oder festgelegt hat, wenn die Anforderung VC-spezifisch war. Andernfalls ist dieser Parameter NULL.

[in] ProtocolPartyContext

Ein Handle, das die Partei auf einer Multipoint-VC identifiziert, für die der Treiber Informationen angefordert oder festgelegt hat, wenn die Anforderung parteispezifisch ist. Andernfalls ist dieser Parameter NULL.

[in, out] OidRequest

Ein Zeiger auf die vom Treiber bereitgestellte NDIS_OID_REQUEST Struktur, die zuvor an die Funktion NdisCoOidRequest oder NdisMCmOidRequest übergeben wurde.

[in] Status

Der letzte status der Anforderung. Der Zieltreiber oder NDIS bestimmt diese endgültige status. Dieser Parameter bestimmt, was ProtocolCoOidRequestComplete mit den Informationen in OidRequest macht.

Rückgabewert

Keine

Bemerkungen

NDIS ruft die ProtocolCoOidRequestComplete-Funktion auf, um die Verarbeitung der CoNDIS-Client-, Aufruf-Manager- oder MCM-OID-Anforderung abzuschließen, für die die NdisCoOidRequest-Funktion oder die NdisMCmOidRequest-Funktion NDIS_STATUS_PENDING zurückgegeben wurde.

Um ProtocolCoOidRequestComplete als Client zu registrieren, initialisiert ein Treiber einen NDIS_CO_CLIENT_OPTIONAL_HANDLERS Struktur und übergibt sie am OptionalHandlers-Parameter der NdisSetOptionalHandlers-Funktion . Um ProtocolCoOidRequestComplete als Anruf-Manager zu registrieren, initialisiert ein Treiber einen NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS Struktur und übergibt sie am OptionalHandlers-Parameter von NdisSetOptionalHandlers.

Der Zieltreiber ist der Treiber, der die OID-Informationsanforderung gewartet hat. Aufruf eines Zieltreibers an die NdisMCoOidRequestComplete, NdisCoOidRequestComplete oder Die NdisMCmOidRequestComplete-Funktion hat dazu geführt, dass NDIS die ProtocolCoOidRequestComplete-Funktion aufruft . NDIS leitet den Wert des Statusparameters , der an diese Funktionen als Eingabestatusparameter übergeben wurde, an ProtocolCoOidRequestComplete weiter.

ProtocolCoOidRequestComplete verwendet den Eingabewert status wie folgt:

Wenn Status NDIS_STATUS_SUCCESS ist, gibt das BytesRead - oder BytesWritten-Element der NDIS_OID_REQUEST-Struktur an, auf die der OidRequest-Parameter verweist, an, wie viele Informationen aus dem Puffer im InformationBuffer-Member von NDIS_OID_REQUEST an den Zieltreiber übertragen wurden bzw. wie viele Informationen bei InformationBuffer zurückgegeben wurden.
Wenn der Treiber eine Abfrageanforderung gestellt hat, kann ProtocolCoOidRequestComplete die in InformationBuffer zurückgegebenen Daten entsprechend dem Wert verwenden, der im Oid-Member von NDIS_OID_REQUEST angegeben ist.
Wenn Status NDIS_STATUS_INVALID_LENGTH oder NDIS_STATUS_BUFFER_TOO_SHORT ist, gibt das BytesNeeded-Element der NDIS_OID_REQUEST-Struktur, auf die OidRequest verweist, den OID-spezifischen Wert des InformationBufferLength-Members von NDIS_OID_REQUEST an, der zum Ausführen des angeforderten Vorgangs erforderlich ist.
Unter diesen Umständen kann ProtocolCoOidRequestComplete ausreichend Pufferspeicher für die Anforderung zuweisen, eine weitere NDIS_OID_REQUEST-Struktur mit dem erforderlichen Wert für InformationBufferLength einrichten und die OID-Anforderung wiederholen.
Wenn Status ein NDIS_STATUS_ XXX-Wert ist, der ein nicht behebbarer Fehler ist, sollte ProtocolCoOidRequestComplete den Arbeitsspeicher für die NDIS_OID_REQUEST-Struktur freigeben. ProtocolCoOidRequestComplete sollte auch bestimmen, ob der Treiber die Bindung schließen oder seine bindungsspezifischen Zustandsinformationen anpassen soll, um weitere Netzwerk-E/A-Vorgänge für die Bindung zu verarbeiten.

Weitere Informationen zu systemdefiniertem OIDs finden Sie unter NDIS-OIDs.

ProtocolCoOidRequestComplete kann aufgerufen werden, bevor der Treiber Zeit hatte, den status Code zu überprüfen, den NdisCoOidRequest oder NdisMCmOidRequest zurückgibt.

NDIS ruft ProtocolCoOidRequestComplete unter IRQL <= DISPATCH_LEVEL auf.

Beispiele

Um eine ProtocolCoOidRequestComplete-Funktion zu definieren, müssen Sie zuerst 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 ProtocolCoOidRequestComplete-Funktion mit dem Namen "MyCoOidRequestComplete" zu definieren, verwenden Sie den PROTOCOL_CO_OID_REQUEST_COMPLETE-Typ , wie in diesem Codebeispiel gezeigt:

PROTOCOL_CO_OID_REQUEST_COMPLETE MyCoOidRequestComplete;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
VOID
 MyCoOidRequestComplete(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

Der PROTOCOL_CO_OID_REQUEST_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_CO_OID_REQUEST_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 in NDIS 6.0 und höher.
Zielplattform	Windows
Kopfzeile	ndis.h (einschließlich Ndis.h)
IRQL	<= DISPATCH_LEVEL (siehe Abschnitt Hinweise)