PROTOCOL_DIRECT_OID_REQUEST_COMPLETE Rückruffunktion (ndis.h)

Artikel
02/26/2024

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

Hinweis Sie müssen die Funktion mithilfe des typs PROTOCOL_DIRECT_OID_REQUEST_COMPLETE deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

PROTOCOL_DIRECT_OID_REQUEST_COMPLETE ProtocolDirectOidRequestComplete;

void ProtocolDirectOidRequestComplete(
  [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 NdisDirectOidRequest-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 ProtocolDirectOidRequestComplete mit den Informationen in OidRequest macht.

Rückgabewert

Keine

Bemerkungen

ProtocolDirectOidRequestComplete ist eine optionale Funktion. Wenn ein Protokolltreiber keine direkten OID-Anforderungen verwendet, kann er den Einstiegspunkt für diese Funktion auf NULL festlegen, wenn er die NdisRegisterProtocolDriver-Funktion .

ProtocolDirectOidRequestComplete verwendet den Eingabewert des Status-Parameters 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. Diese Werte geben an, wie viele vom Protokolltreiber bereitgestellte Informationen aus dem Puffer bei InformationBuffer in die NIC in einem set-Vorgang übertragen wurden oder wie viele Informationen bei InformationBuffer als Reaktion auf einen Abfragevorgang zurückgegeben wurden.
Wenn der Protokolltreiber eine Abfrage durchgeführt hat, kann ProtocolDirectOidRequestComplete die daten, die an InformationBuffer zurückgegeben werden, 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 ProtocolDirectOidRequestComplete Zustandsvariablen im Bereich ProtocolBindingContext einrichten, um die Anzahl der ausstehenden Sendevorgänge zu drosseln, die der Treiber für nachfolgende Aufrufe von NdisSendNetBufferLists-Funktion .
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 ProtocolDirectOidRequestComplete ausreichend Pufferspeicherplatz für die Anforderung zuweisen, eine weitere NDIS_OID_REQUEST-Struktur mit dem erforderlichen InformationBufferLength-Wert und demselben Oid-Wert einrichten und den Aufruf der NdisDirectOidRequest-Funktion wiederholen.

ProtocolDirectOidRequestComplete kann Anforderungen für bestimmte andere NDIS_STATUS_ Xxx-Argumente wiederholen, wie unter NdisDirectOidRequest beschrieben.
Wenn Status ein NDIS_STATUS_ Xxx-Wert ist, bei dem es sich um einen nicht behebbaren Fehler handelt, sollte ProtocolDirectOidRequestComplete den Speicher freigeben, der der NDIS_OID_REQUEST-Struktur zugeordnet ist, und bestimmen, ob der Treiber die Bindung schließen oder seine bindungsspezifischen Statusinformationen anpassen soll, um fortgesetzte Netzwerk-E/A-Vorgänge für die Bindung zu verarbeiten.

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

NDIS ruft ProtocolDirectOidRequestComplete unter IRQL <= DISPATCH_LEVEL auf.

Beispiele

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

PROTOCOL_DIRECT_OID_REQUEST_COMPLETE MyDirectOidRequestComplete;

Implementieren Sie dann Ihre Funktion wie folgt:

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

Der PROTOCOL_DIRECT_OID_REQUEST_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_DIRECT_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.1 und höher.
Zielplattform	Windows
Kopfzeile	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL