PROTOCOL_OID_REQUEST_COMPLETE Rückruffunktion (ndis.h)

Artikel
08/07/2023

Die ProtocolOidRequestComplete-Funktion schließt die Verarbeitung einer vom Protokolltreiber initiierten OID-Anforderung ab, für die die NdisOidRequest-Funktion NDIS_STATUS_PENDING zurückgegeben hat.

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

Syntax

PROTOCOL_OID_REQUEST_COMPLETE ProtocolOidRequestComplete;

void ProtocolOidRequestComplete(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNDIS_OID_REQUEST OidRequest,
  [in] NDIS_STATUS Status
)
{...}

Parameter

[in] ProtocolBindingContext

Ein Handle für einen vom Protokolltreiber zugewiesenen Kontextbereich, in dem der Protokolltreiber den Laufzeitzustand pro Bindung verwaltet. Der Treiber hat dieses Handle bereitgestellt, als er die NdisOpenAdapterEx-Funktion aufgerufen hat.

[in] OidRequest

Ein Zeiger auf die vom Protokolltreiber bereitgestellte NDIS_OID_REQUEST Struktur, die zuvor an die NdisOidRequest-Funktion übergeben wurde.

[in] Status

Die endgültige status der Anforderung. Der zugrunde liegende Treiber oder die zugrunde liegende NDIS bestimmt diese endgültige status. Dieser Parameter bestimmt, was ProtocolOidRequestComplete mit den Informationen in OidRequest macht.

Rückgabewert

Keine

Bemerkungen

ProtocolOidRequestComplete verwendet den Eingabewert von Status wie folgt:

Wenn Status NDIS_STATUS_SUCCESS ist, wurde das BytesRead - oder BytesWritten-Element der NDIS_OID_REQUEST-Struktur von NDIS oder dem zugrunde liegenden Treiber festgelegt, um anzugeben, wie viele vom Protokolltreiber bereitgestellte Informationen aus dem Puffer bei InformationBuffer in die NIC in einem Set-Vorgang übertragen wurden oder wie viele Informationen an InformationBuffer als Reaktion auf einen Abfragevorgang zurückgegeben wurden.
Wenn der Protokolltreiber eine Abfrage durchgeführt hat, kann ProtocolOidRequestComplete die an InformationBuffer zurückgegebenen Daten in beliebiger Weise verwenden, die vom Protokolltreiber abhängig vom Wert des Oid-Elements bestimmt wird.

Wenn der Protokolltreiber z. B. ursprünglich eine OID_GEN_MAXIMUM_SEND_PACKETS Abfrage kann ProtocolOidRequestComplete Zustandsvariablen im Bereich ProtocolBindingContext einrichten, um die Anzahl der ausstehenden Sendevorgänge zu drosseln, die der Treiber für nachfolgende Aufrufe der NdisSendNetBufferLIsts-Funktion eingerichtet hat.
Wenn Status NDIS_STATUS_INVALID_LENGTH oder NDIS_STATUS_BUFFER_TOO_SHORT ist, gibt das BytesNeeded-Element den OID-spezifischen Wert des InformationBufferLength-Elements an, der zum Ausführen des angeforderten Vorgangs erforderlich ist.
Unter diesen Umständen kann ProtocolOidRequestComplete ausreichend Pufferspeicherplatz für die Anforderung zuweisen, eine weitere NDIS_OID_REQUEST-Struktur mit dem erforderlichen InformationBufferLength und demselben Oid einrichten und den Aufruf der NdisOidRequest-Funktion wiederholen.

ProtocolOidRequestComplete kann Anforderungen für bestimmte andere NDIS_STATUS_ XXX-Argumente wiederholen, wie in der Referenz für die NdisOidRequest-Funktion beschrieben.
Wenn Status ein NDIS_STATUS_ XXX-Wert ist, bei dem es sich um einen nicht behebbaren Fehler handelt, sollte ProtocolOidRequestComplete den der NDIS_OID_REQUEST-Struktur zugeordneten Arbeitsspeicher freigeben und bestimmen, ob der Treiber die Bindung schließen oder seine bindungsspezifischen Zustandsinformationen anpassen soll, um fortgesetzte Netzwerk-E/A-Vorgänge für die Bindung zu verarbeiten.

Bei globalen Abfragen und Sätzen bewirkt der Aufruf des zugrunde liegenden verbindungslosen Miniporttreibers an die NdisMOidRequestComplete-Funktion , dass NDIS die ProtocolOidRequestComplete-Funktion aufruft . NDIS leitet den vom Miniporttreiber ermittelten Status , der an NdisMOidRequestComplete übergeben wird, als Eingabestatus an ProtocolOidRequestComplete weiter.

Für bindungsspezifische Abfragen ruft NDIS die ProtocolOidRequestComplete-Funktion selbst auf. Da die NDIS-Bibliothek Bindungen für alle Miniporttreiber verwaltet, kann NDIS bindungsspezifische Informationen nur zu zugrunde liegenden Treibern zurückgeben, die ihren mittleren Typ als einen melden, für den das System eine Filterbibliothek bereitstellt. NDIS gibt NDIS_STATUS_NOT_SUPPORTED für vom Protokolltreiber initiierte Bindungsabfragen an andere Miniporttreiber zurück.

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

ProtocolOidRequestComplete kann aufgerufen werden, bevor der Protokolltreiber Zeit hatte, den status Code zu überprüfen, den NdisOidRequest unter Status zurückgibt.

NDIS ruft ProtocolOidRequestComplete unter IRQL <= DISPATCH_LEVEL auf.

Beispiele

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

PROTOCOL_OID_REQUEST_COMPLETE MyOidRequestComplete;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
VOID
 MyOidRequestComplete(
    NDIS_HANDLE  ProtocolBindingContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

Der PROTOCOL_OID_REQUEST_COMPLETE Funktionstyp ist in der Ndis.h-Headerdatei 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_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 (include Ndis.h)
IRQL	<= DISPATCH_LEVEL