SET_OPTIONS Rückruffunktion (ndis.h)
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.
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 |
|---|---|
|
XxxSetOptions hat die optionalen Dienste und Ressourcen des Treibers erfolgreich registriert. |
|
XxxSetOptions konnte die vom Treiber benötigten Ressourcen nicht zuordnen. |
|
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);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 |