FILTER_OID_REQUEST Rückruffunktion (ndis.h)

Artikel
08/07/2023

NDIS ruft die FilterOidRequest-Funktion eines Filtertreibers auf, um eine OID-Anforderung zu verarbeiten, die dem angegebenen Filtermodul zugeordnet ist.

Hinweis Sie müssen die Funktion mit dem FILTER_OID_REQUEST-Typ deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

FILTER_OID_REQUEST FilterOidRequest;

NDIS_STATUS FilterOidRequest(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_OID_REQUEST OidRequest
)
{...}

Parameter

[in] 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] OidRequest

Ein Zeiger auf eine NDIS_OID_REQUEST-Struktur , die den angeforderten Vorgang einschließlich des OID_XXX-Codes angibt. Die Struktur kann entweder eine OID-Abfrageanforderung oder eine OID-Set-Anforderung angeben. Weitere Informationen zu OIDs finden Sie unter NDIS-OIDs.

Rückgabewert

FilterOidRequest gibt einen der folgenden status Werte zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	FilterOidRequest hat den Abfrage- oder Setvorgang des Filtertreibers für dieses Filtermodul erfolgreich abgeschlossen.
NDIS_STATUS_PENDING	Gibt an, dass der Filtertreiber die Anforderung asynchron abschließt. Nachdem der Treiber die Anforderung abgeschlossen hat, muss er die NdisFOidRequestComplete-Funktion , um NDIS darüber zu informieren, dass die Anforderung abgeschlossen ist.
NDIS_STATUS_INVALID_OID	Gibt an, dass die Anforderung, die in OidRequest angegeben wird, ungültig oder nicht erkannt ist.
NDIS_STATUS_NOT_SUPPORTED	FilterOidRequest unterstützt die OID nicht, die OID ist optional.
NDIS_STATUS_BUFFER_TOO_SHORT	Gibt an, dass der bei OidRequest bereitgestellte Puffer zu klein ist, um die angeforderten Daten aufzunehmen.
NDIS_STATUS_INVALID_LENGTH	Bei einem Abfragevorgang entspricht das InformationBufferLength-Element der NDIS_OID_REQUEST-Struktur nicht der Länge, die für die angegebene OID erforderlich ist. FilterOidRequest hat die erforderliche Puffergröße in Bytes im BytesNeed-Element der NDIS_OID_REQUEST-Struktur zurückgegeben.
NDIS_STATUS_INVALID_DATA	Bei einem Setvorgang waren die im InformationBuffer-Member der NDIS_OID_REQUEST-Struktur angegebenen Daten für die angegebene OID ungültig.
NDIS_STATUS_NOT_ACCEPTED	FilterOidRequest hat versucht, die angeforderten Informationen zu sammeln, war jedoch nicht erfolgreich.
NDIS_STATUS_RESOURCES	FilterOidRequest ist aufgrund unzureichender Ressourcen fehlgeschlagen.
NDIS_STATUS_FAILURE	FilterOidRequest gibt NDIS_STATUS_FAILURE zurück, wenn keiner der vorherigen Werte zutrifft. Der Filtertreiber sollte die NdisWriteErrorLogEntry-Funktion mit Parametern aufrufen, die den Grund für den Fehler angeben.

Hinweise

FilterOidRequest ist eine optionale Funktion. Wenn ein Filtertreiber keine OID-Anforderungen verwendet, kann er den Einstiegspunkt für diese Funktion auf NULL festlegen, wenn er die NdisFRegisterFilterDriver-Funktion aufruft. Wenn ein Filtertreiber eine FilterOidRequestComplete-Funktion definiert, muss er die FilterOidRequest-Funktion bereitstellen.

NDIS ruft die FilterOidRequest-Funktion des Filtertreibers auf, um OID-Anforderungen zu verarbeiten, die von überlastenden Treibern stammen. Filtertreiber können solche Anforderungen an zugrunde liegende Treiber weiterleiten, indem sie die NdisFOidRequest-Funktion aufrufen.

Bevor der Treiber NdisFOidRequest aufruft, muss der Treiber eine NDIS_OID_REQUEST Struktur zuweisen und die Anforderungsinformationen durch Aufrufen von NdisAllocateCloneOidRequest an die neue Struktur übertragen. Optional kann ein Filtertreiber eine Anforderung sofort ausführen, ohne die Anforderung weiterzuleiten.

Um eine Anforderung synchron abzuschließen, gibt der Filtertreiber NDIS_STATUS_SUCCESS oder einen Fehler status zurück. Wenn der Treiber NDIS_STATUS_PENDING zurückgibt, muss er die NdisFOidRequestComplete-Funktion aufrufen, um NDIS darüber zu informieren, dass die Anforderung abgeschlossen ist.

Für einen Abfragevorgang gibt FilterOidRequest die angeforderten Informationen im InformationBuffer-Member zurück und legt die Variable im BytesWritten-Member der NDIS_OID_REQUEST-Struktur auf die Menge der zurückgegebenen Informationen fest. Die zugrunde liegenden Treiber tun dies, wenn der Filtertreiber die Anforderung mit NdisFOidRequest übergeben hat.

Für einen Setvorgang kann FilterOidRequest die Daten im InformationBuffer-Member der NDIS_OID_REQUEST-Struktur verwenden, um die für die angegebene OID erforderlichen Informationen festzulegen. In diesem Fall legt FilterOidRequest die Variable bei BytesRead auf die Menge der bereitgestellten Daten fest, die sie verwendet hat. Die zugrunde liegenden Treiber tun dies, wenn der Filtertreiber die Anforderung mit NdisFOidRequest übergeben hat.

Wie Miniporttreiber können Filtertreiber jeweils nur eine Anforderung empfangen. NDIS serialisiert Anforderungen, die an einen Filtertreiber gesendet werden. NDIS kann FilterOidRequest nicht aufrufen, bevor ein Filtertreiber die aktuelle Anforderung abgeschlossen hat.

NDIS ruft FilterOidRequest bei IRQL <= DISPATCH_LEVEL auf.

Beispiele

Um eine FilterOidRequest-Funktion zu definieren, müssen Sie zunächst 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 FilterOidRequest-Funktion mit dem Namen "MyOidRequest" zu definieren, verwenden Sie den FILTER_OID_REQUEST-Typ , wie in diesem Codebeispiel gezeigt:

FILTER_OID_REQUEST MyOidRequest;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyOidRequest(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

Der FILTER_OID_REQUEST Funktionstyp ist in der Ndis.h-Headerdatei 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 FILTER_OID_REQUEST 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