FILTER_DIRECT_OID_REQUEST Rückruffunktion (ndis.h)

Artikel
08/07/2023

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

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

Syntax

FILTER_DIRECT_OID_REQUEST FilterDirectOidRequest;

NDIS_STATUS FilterDirectOidRequest(
  [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_ Xx-Codes angibt. Die -Struktur kann entweder eine Abfrageanforderung oder eine festgelegte Anforderung angeben.

Rückgabewert

FilterDirectOidRequest gibt einen der folgenden status Werte zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	FilterDirectOidRequest hat den Abfrage- oder Setvorgang des Filtertreibers für dieses Filtermodul erfolgreich abgeschlossen.
NDIS_STATUS_PENDING	Der Filtertreiber führt die Anforderung asynchron aus. Nachdem der Treiber die Anforderung abgeschlossen hat, muss er die NdisFDirectOidRequestComplete-Funktion , um NDIS darüber zu informieren, dass die Anforderung abgeschlossen ist.
NDIS_STATUS_INVALID_OID	Die von OidRequest angegebene Anforderung war ungültig oder nicht erkannt.
NDIS_STATUS_NOT_SUPPORTED	FilterDirectOidRequest unterstützt die OID nicht. die OID ist optional.
NDIS_STATUS_BUFFER_TOO_SHORT	Der von OidRequest bereitgestellte Puffer war zu klein, um die angeforderten Daten zu speichern.
NDIS_STATUS_INVALID_LENGTH	Bei einem Abfragevorgang stimmt der InformationBufferLength-Member der NDIS_OID_REQUEST-Struktur nicht mit der Länge überein, die die angegebene OID benötigt. FilterDirectOidRequest hat die erforderliche Puffergröße in Bytes im BytesNeeded-Element der NDIS_OID_REQUEST-Struktur zurückgegeben.
NDIS_STATUS_INVALID_DATA	Bei einem Set-Vorgang waren die Daten, die im InformationBuffer-Member der NDIS_OID_REQUEST-Struktur angegeben wurden, für die angegebene OID ungültig.
NDIS_STATUS_NOT_ACCEPTED	FilterDirectOidRequest hat versucht, die angeforderten Informationen zu sammeln, war jedoch nicht erfolgreich.
NDIS_STATUS_RESOURCES	Fehler bei FilterDirectOidRequest aufgrund unzureichender Ressourcen.
NDIS_STATUS_FAILURE	N einer der vorherigen Rückgabewerte gilt. Der Filtertreiber sollte die NdisWriteErrorLogEntry-Funktion mit Parametern aufrufen, die den Grund für den Fehler angeben.

Hinweise

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

NDIS ruft die FilterDirectOidRequest-Funktion des Filtertreibers auf, um direkte OID-Anforderungen zu verarbeiten, die von übergeordneten Treibern stammen. Filtertreiber können solche Anforderungen an zugrunde liegende Treiber weiterleiten, indem sie die NdisFDirectOidRequest-Funktion aufrufen. Optional kann ein Filtertreiber auch eine Anforderung sofort ausführen, ohne die Anforderung weiterzuleiten.

Bevor der Treiber NdisFDirectOidRequest aufruft, muss der Treiber eine NDIS_OID_REQUEST Struktur zuordnen und die Anforderungsinformationen an die neue Struktur übertragen, indem er die NdisAllocateCloneOidRequest-Funktion .

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 NdisFDirectOidRequestComplete-Funktion , um NDIS darüber zu informieren, dass die Anforderung abgeschlossen ist.

Für einen Abfragevorgang gibt FilterDirectOidRequest 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 NdisFDirectOidRequest übergeben hat.

Für einen Set-Vorgang kann FilterDirectOidRequest die Daten im InformationBuffer-Member der NDIS_OID_REQUEST-Struktur verwenden, um die Informationen festzulegen, die die angegebene OID benötigt. In diesem Fall legt FilterDirectOidRequest die Variable auf BytesRead auf die Menge der bereitgestellten Daten fest, die sie verwendet hat. Die zugrunde liegenden Treiber legen BytesRead auf diese Weise fest, wenn der Filtertreiber die Anforderung mit NdisFDirectOidRequest übergeben hat.

NDIS serialisiert keine Anforderungen, die an FilterDirectOidRequest mit anderen OID-Anforderungen gesendet werden. Der Filtertreiber muss in der Lage sein, mehrere Aufrufe von FilterDirectOidRequest zu verarbeiten, wenn andere Anforderungen, die an FilterOidRequest oder FilterDirectOidRequest gesendet werden, ausstehen.

NDIS ruft FilterDirectOidRequest unter IRQL <= DISPATCH_LEVEL auf.

Beispiele

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

FILTER_DIRECT_OID_REQUEST MyDirectOidRequest;

Implementieren Sie dann Ihre Funktion wie folgt:

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

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