Freigeben über

FILTER_SYNCHRONOUS_OID_REQUEST-Funktion (ndis.h)

  • Artikel

NDIS ruft die FilterSynchronousOidRequest-Funktion eines Filtertreibers auf, um eine Vorschau einer synchronen OID-Anforderung anzuzeigen, bevor die Anforderung an den zugrunde liegenden Miniporttreiber übergeben wird.

Diese Funktion wird in NDIS 6.81 und höher unterstützt.

Syntax

NDIS_STATUS FILTER_SYNCHRONOUS_OID_REQUEST(
            NDIS_HANDLE      FilterModuleContext,
  [in, out] NDIS_OID_REQUEST *OidRequest,
  [out]     PVOID            *CallContext
);

Parameter

FilterModuleContext

Ein Handle für den Kontextbereich für das Filtermodul, das das Ziel dieser Anforderung ist. Der Filtertreiber hat diesen Kontextbereich in der FilterAttach-Funktion erstellt und initialisiert.

[in, out] OidRequest

Ein Zeiger auf eine NDIS_OID_REQUEST-Struktur , die den angeforderten Vorgang angibt.

[out] CallContext

Ein PVOID-großer Speicherslot für den Filtertreiber, um den Zustand zwischen den Handlern FilterSynchronousOidRequest und FilterSynchronousOidRequestComplete gemeinsam nutzen zu können. NDIS garantiert, dass dies zunächst auf einen Nullwert verweist. Weitere Informationen finden Sie im Abschnitt Hinweise.

Rückgabewert

Diese Funktion gibt einen der folgenden geeigneten NDIS_STATUS-Codes zurück:

Rückgabecode Beschreibung
NDIS_STATUS_SUCCESS Zulassen, dass die OID-Anforderung weiterhin an den Miniporttreiber weitergegeben wird. Filtertreiber müssen diesen status Code für jeden nicht erkannten Typ von OID zurückgeben.
NDIS_STATUS_ALREADY_COMPLETE Beenden Sie die Weitergabe der OID-Anforderung nach unten, und geben Sie sie stattdessen mit dem status NDIS_STATUS_SUCCESS an den Aufrufer zurück.
  • NDIS_STATUS_BUFFER_TOO_SHORT
  • NDIS_STATUS_INVALID_LENGTH
  • NDIS_STATUS_INVALID_DATA
 Identisch mit FilterDirectOidRequest.
NDIS_STATUS_RESOURCES Identisch mit FilterDirectOidRequest, aber mit einer Vorsicht, dass synchrone OID-Anforderungen schnell abgeschlossen werden müssen, und daher sollten Filtertreiber in der Regel vermeiden, Ressourcen zuzuweisen.
NDIS_STATUS_NOT_SUPPORTED Filtertreiber dürfen diesen Code nicht zurückgeben, nur weil die OID nicht erkannt ist. Filtertreiber geben dies möglicherweise nur zurück, wenn der Filter den Vorgang erkennt, ihn aber aus irgendeinem Grund nicht ausführen kann.

Hinweise

FilterSynchronousOidRequest ist eine optionale Funktion. Wenn ein Filtertreiber keine synchronen OID-Anforderungen an den Miniporttreiber beobachten oder ändern muss, sollte der Filtertreiber den Einstiegspunkt für diese Funktion auf NULL festlegen, wenn er NdisFRegisterFilterDriver aufruft.

NDIS ruft die FilterSynchronousOidRequest-Funktion des Filtertreibers auf, um synchrone OID-Anforderungen zu verarbeiten, die von überlastenden Treibern stammen. Filtertreiber können einige Felder in der NDIS_OID_REQUEST-Struktur wie folgt lesen oder ändern:

Feld Filterzugriff
Header Schreibgeschützt
RequestType Lesen/Schreiben
PortNumber Lesen/Schreiben
Timeout Nicht zugreifen
RequestId Nicht zugreifen
RequestHandle Lesen/Schreiben
DATA Lesen/Schreiben
NdisReserved Nicht zugreifen
MiniportReserved Nicht zugreifen
SourceReserved Nicht zugreifen
SupportedRevision Lesen/Schreiben
Reserviert1, Reserviert2 Nicht zugreifen
SwitchId Lesen/Schreiben
VPortId Lesen/Schreiben
Flags Lesen/Schreiben

Zusätzlich zum Ändern der NDIS_OID_REQUEST-Struktur können Filtertreiber die Anforderung mithilfe des Rückgabecodes von FilterSynchronousOidRequest steuern:

  • NDIS_STATUS_SUCCESS: Die OID wird weiterhin an den Miniporttreiber weitergegeben.
  • NDIS_STATUS_ALREADY_COMPLETE: Die OID wird sofort zurück an die darüber stehenden Treiber abgeschlossen, ohne sich zuerst an den Miniporttreiber weiterzuverbreiten. Die OID-Anforderung wird an den überlastenden Treiber mit NDIS_STATUS_SUCCESS abgeschlossen.
  • Jeder andere status Code: Die OID wird sofort zurück an die darüber stehenden Treiber abgeschlossen, ohne zuerst an den Miniporttreiber weiterzuverbreiten. Die OID-Anforderung wird an den überlastenden Treiber mit dem vom Filtertreiber zurückgegebenen status-Code abgeschlossen.

Wenn der Filtertreiber auch einen FilterSynchronousOidRequestComplete-Handler registriert, garantiert NDIS, dass der FilterSynchronousOidRequestComplete-Handler nur aufgerufen wird, wenn der FilterSynchronousOidRequest-Handler NDIS_STATUS_SUCCESS zurückgibt.

Der FilterSynchronousOidRequest-Handler kann einen beliebigen PVOID-Wert in *CallContext schreiben, und derselbe Wert wird an den FilterSynchronousOidRequestComplete-Handler des Filtertreibers zurückgegeben, wenn die OID-Anforderung abgeschlossen ist. Der Filtertreiber kann dies verwenden, um den Zustand über die beiden Handler hinweg zu übertragen. Da der FilterSynchronousOidRequestComplete-Handler nur aufgerufen wird, wenn der FilterSynchronousOidRequest-Handler NDIS_STATUS_SUCCESS zurückgibt, gibt es keinen Grund, einen Wert in *CallContext zu schreiben, wenn ein anderer Code zurückgegeben wird. Ebenso gibt es keinen Grund, einen Wert in *CallContext zu schreiben, wenn der Filtertreiber keinen FilterSynchronousOidRequestComplete-Handler bereitstellt.

Filtertreiber dürfen keine NDIS_STATUS_PENDING von einem FilterSynchronousOidRequest-Handler zurückgeben. Synchrone OID-Anforderungen können nicht geschrieben oder abgebrochen werden.

Es wird erwartet, dass Filtertreiber schnell von ihrem FilterSynchronousOidRequest-Handler zurückkehren, ohne zu blockieren, zu warten oder zu schlafen. Synchrone OID-Anforderungen werden nur für Vorgänge mit geringer Latenz verwendet, und Filtertreiber sollten versuchen, sie innerhalb von mehreren Millisekunden fortzusetzen oder abzuschließen. NDIS serialisiert keine synchronen OID-Anforderungen gegeneinander, für andere OID-Anforderungen oder für FilterPause. Es liegt in der Verantwortung des Filtertreibers, die erforderliche Synchronisierung zu implementieren.

NDIS serialisiert synchrone OID-Anforderungen für FilterDetach: NDIS garantiert, dass nach dem Aufruf von FilterDetach keine synchronen OID-Anforderungen aktiv sind.

Filtertreiber dürfen NdisAllocateCloneOidRequest oder NdisCancelOidRequest für eine synchrone OID-Anforderung nicht aufrufen. Filtertreiber dürfen NdisFSynchronousOidRequest nicht für eine OID-Anforderung aufrufen, die über einen FilterSynchronousOidRequest-Handler empfangen wird.

Wenn ein Filtertreiber den IRQL in seinem FilterSynchronousOidRequest-Handler auslöst, muss er den IRQL auf die ursprüngliche Ebene wiederherstellen, bevor er von seinem FilterSynchronousOidRequest-Handler zurückgibt.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 10, Version 1709
Zielplattform Windows
Kopfzeile ndis.h (einschließlich Ndis.h)
IRQL <= DISPATCH_LEVEL

Weitere Informationen

FilterSynchronousOidRequestComplete

NdisFSynchronousOidRequest

Synchrone OID-Anforderungsschnittstelle in NDIS 6.80