SET_OPTIONS Rückruffunktion (ndis.h)

2025-02-07

NDIS ruft die XxxSetOptions--Funktion eines Treibers auf, damit der Treiber optionale Dienste registrieren kann. Diese Funktion wird als MiniportSetOptions- für Miniporttreiber definiert, ProtocolSetOptions- für Protokolltreiber oder FilterSetOptions- für Filtertreiber.

Hinweis Sie müssen die Funktion mithilfe des Xxx_SET_OPTIONS Typs deklarieren. Weitere Informationen finden Sie im Abschnitt "Beispiele".

Syntax

SET_OPTIONS SetOptions;

NDIS_STATUS SetOptions(
  [in] NDIS_HANDLE NdisDriverHandle,
  [in] NDIS_HANDLE DriverContext
)
{...}

Parameter

[in] NdisDriverHandle

Ein Handle, das einen Treiber identifiziert. NDIS gibt dieses Handle an den Treiber zurück, wenn es von der Treiberregistrierungsfunktion zurückgegeben wird ( NdisMRegisterMiniportDriver für Miniporttreiber, NdisRegisterProtocolDriver für Protokolltreiber und NdisFRegisterFilterDriver für Filtertreiber).

[in] DriverContext

Das Handle, das der Treiber an NdisRegisterXxxDriver übergeben hat, der den Kontextbereich des Treibers identifiziert, wobei Xxx der Typ des Treibers ist (Miniport, Protokoll oder Filter).

Rückgabewert

XxxSetOptions- gibt einen der folgenden Statuswerte zurück:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	XxxSetOptions die optionalen Dienste und Ressourcen des Treibers erfolgreich registriert.
NDIS_STATUS_RESOURCES	XxxSetOptions- konnten die vom Treiber benötigten Ressourcen nicht zuordnen.
NDIS_STATUS_XXX oder NTSTATUS_XXX	Fehler beim Versuch des Treibers, Optionen zu registrieren. In der Regel wird ein solcher Fehlerstatus von einer NdisXxx--Funktion oder einer Kernelmodusunterstützungsroutine weitergegeben.

Bemerkungen

XxxSetOptions- ist eine optionale Funktion. NDIS ruft XxxSetOptions- im Kontext des Treiberaufrufs an den NdisRegisterXxxDriver Funktion, wobei Xxx der Typ des Treibers ist (Miniport, Protokoll oder Filter).

XxxSetOptions optionale Dienste registriert und andere Treiberressourcen zuordnen kann. Um optionale MiniportXxx-, ProtocolXxx-oder FilterXxx--Funktionen zu registrieren, ruft der Treiber die NdisSetOptionalHandlers-Funktion auf. Der Treiber übergibt das Handle vom NdisDriverHandle Parameter an der NdisHandle Parameter von NdisSetOptionalHandlers und übergibt eine Eigenschaftenstruktur an den OptionalHandlers Parameter.

Miniport-Treiber können auf die optionalen Dienste angewendet werden, die in den folgenden Merkmalen definiert sind:

NDIS_MINIPORT_CO_CHARACTERISTICS

NDIS_MINIPORT_PNP_CHARACTERISTICS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS(siehe NDIS 6.0 TCP Chimney Offload-Dokumentation)

NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS(siehe NDIS 6.0 TCP Chimney Offload-Dokumentation)

Protokolltreiber können auf die in den folgenden Eigenschaftenstrukturen definierten optionalen Dienste angewendet werden:

NDIS_PROTOCOL_CO_CHARACTERISTICS

NDIS_CO_CLIENT_OPTIONAL_HANDLERS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

Es gibt keine optionalen Filtertreiberdienste in der aktuellen Windows-Version.

NDIS kann die anderen MiniportXxx-, ProtocolXxx-oder FilterXxx- Funktionen jederzeit aufrufen, nachdem XxxSetOptions zurückgegeben wurde. Der Treiber sollte bereit sein, bei seiner Initialisierungsfunktion zurückgerufen zu werden:(MiniportInitializeEx für Miniporttreiber, ProtocolBindAdapterEx für Protokolltreiber und FilterAttach für Filtertreiber).

Bei Miniporttreibern befinden sich die Miniportadapter im Zustand Angehaltenen, bevor die NDIS MiniportInitializeEx-aufruft. Bei Protokolltreibern befinden sich die Protokollbindungen im Ungebundenen Zustand, bevor NDIS ProtocolBindAdapterExaufruft. Bei Filtertreibern befinden sich die Filtermodule im Zustand Getrennten, bevor NDIS FilterAttach-aufruft.

Wenn beim Versuch, Ressourcen oder Dienste zuzuweisen, ein Fehler auftritt, sollten XxxSetOptions- alle erfolgreichen Zuordnungen rückgängig machen, bevor sie die Steuerung mit einem anderen Status als NDIS_STATUS_SUCCESS zurückgibt.

Die XxxDriverUnload- der Miniport- und Filtertreiber sollten alle Vorgänge rückgängigmachen, die in XxxSetOptions-

NDIS ruft XxxSetOptions- bei IRQL = PASSIVE_LEVEL auf.

beispiele für

Um eine XxxSetOptions--Funktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration angeben, die den Typ der Funktion identifiziert, die Sie definieren. Windows stellt eine Reihe von Funktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Funktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

In der Ndis.h-Headerdatei wird die SET_OPTIONS Rückruffunktion wie folgt weiter definiert:

typedef SET_OPTIONS (*SET_OPTIONS_HANDLER);
typedef SET_OPTIONS (MINIPORT_SET_OPTIONS);
typedef SET_OPTIONS (PROTOCOL_SET_OPTIONS);
typedef SET_OPTIONS (FILTER_SET_OPTIONS);

Dadurch können alle NDIS-Treiber ihre XxxSetOptions-Rückruffunktionen mit derselben Syntax implementieren. Miniporttreiber verwenden den MINIPORT_SET_OPTIONS Typ, Protokolltreiber verwenden den PROTOCOL_SET_OPTIONS Typ, und Filtertreiber verwenden den FILTER_SET_OPTIONS Typ.

Um beispielsweise eine MiniportSetOptions--Funktion zu definieren, die den Namen "MySetOptions" hat, verwenden Sie den MINIPORT_SET_OPTIONS Typ, wie in diesem Codebeispiel gezeigt:

MINIPORT_SET_OPTIONS MySetOptions;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MySetOptions(
    NDIS_HANDLE  NdisDriverHandle,
    NDIS_HANDLE  DriverContext
    )
  {...}

Der SET_OPTIONS Funktionstyp wird in der Ndis.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzufügen. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen, die auf den SET_OPTIONS Funktionstyp in der Headerdatei angewendet werden, verwendet 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_annotationsfinden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Unterstützt in NDIS 6.0 und höher.
Zielplattform-	Fenster
Header-	ndis.h (include Ndis.h)
IRQL-	PASSIVE_LEVEL