SET_OPTIONS Rückruffunktion (ndis.h)

Artikel
02/29/2024

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

Hinweis Sie müssen die Funktion mit dem Xxx_SET_OPTIONS-Typ 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ückgibt ( NdisMRegisterMiniportDriver für Miniporttreiber, NdisRegisterProtocolDriver für Protokolltreiber und NdisFRegisterFilterDriver für Filtertreiber).

[in] DriverContext

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

Rückgabewert

XxxSetOptions gibt einen der folgenden status Werte zurück:

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

Hinweise

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

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

Miniporttreiber können auf die optionalen Dienste angewendet werden, die in den folgenden Eigenschaftenstrukturen 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-Schornsteinabladungsdokumentation)

NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS(siehe NDIS 6.0 TCP-Schornsteinabladungsdokumentation)

Protokolltreiber können auf die optionalen Dienste angewendet werden, die in den folgenden Eigenschaftenstrukturen definiert sind:

NDIS_PROTOCOL_CO_CHARACTERISTICS

NDIS_CO_CLIENT_OPTIONAL_HANDLERS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

In der aktuellen Windows-Version gibt es keine optionalen Filtertreiberdienste.

NDIS kann die anderen Funktionen MiniportXxx, ProtocolXxx oder FilterXxx des Treibers jederzeit aufrufen, nachdem XxxSetOptions zurückgegeben wurde. Der Treiber sollte darauf vorbereitet 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 Angehalten , bevor die NDIS MiniportInitializeEx aufruft. Bei Protokolltreibern befinden sich die Protokollbindungen im Ungebundenen Zustand, bevor die NDIS ProtocolBindAdapterEx aufruft. Bei Filtertreibern befinden sich die Filtermodule im Status "Getrennt" , bevor die NDIS FilterAttach aufruft.

Wenn der Versuch, Ressourcen oder Dienste zuzuweisen, fehlschlägt, sollte XxxSetOptions alle erfolgreichen Zuordnungen rückgängig machen, bevor die Steuerung mit einem anderen status als NDIS_STATUS_SUCCESS zurückgegeben wird.

XxxDriverUnload von Miniport- und Filtertreibern sollte alle Vorgänge rückgängigmachen, die in XxxSetOptions ausgeführt wurden.

NDIS ruft XxxSetOptions unter IRQL = PASSIVE_LEVEL auf.

Beispiele

Um eine XxxSetOptions-Funktion zu definieren, müssen Sie zuerst 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.

In der Ndis.h-Headerdatei wird die SET_OPTIONS Rückruffunktion wie folgt 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 der gleichen Syntax implementieren. Miniporttreiber verwenden den MINIPORT_SET_OPTIONS-Typ , Protokolltreiber den PROTOCOL_SET_OPTIONS-Typ und Filtertreiber den FILTER_SET_OPTIONS-Typ .

Um beispielsweise eine MiniportSetOptions-Funktion mit dem Namen "MySetOptions" zu definieren, 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 ist in der Headerdatei Ndis.h 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 SET_OPTIONS 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	PASSIVE_LEVEL