MINIPORT_CO_OID_REQUEST Rückruffunktion (ndis.h)

Artikel
08/07/2023

Die MiniportCoOidRequest-Funktion verarbeitet eine OID-Anforderung, um Informationen im CoNDIS-Miniporttreiber abzufragen oder festzulegen.

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

Syntax

MINIPORT_CO_OID_REQUEST MiniportCoOidRequest;

NDIS_STATUS MiniportCoOidRequest(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] NDIS_HANDLE MiniportVcContext,
       PNDIS_OID_REQUEST NdisRequest
)
{...}

Parameter

[in] MiniportAdapterContext

Ein Handle für einen Kontextbereich, den der Miniporttreiber in seiner MiniportInitializeEx-Funktion zugeordnet hat. Der Miniporttreiber verwendet diesen Kontextbereich, um Zustandsinformationen für einen Miniportadapter zu verwalten.

[in] MiniportVcContext

Ein Handle für einen vom Miniporttreiber zugewiesenen Kontextbereich, in dem der Miniporttreiber seinen Status pro virtueller Verbindung (VC) beibehält. Der Miniporttreiber hat dieses Handle über seine MiniportCoCreateVc-Funktion für NDIS bereitgestellt. Wenn die Anforderung nicht VC-spezifisch ist, ist dieser Parameter NULL.

NdisRequest

Ein Zeiger auf eine NDIS_OID_REQUEST Struktur, die sowohl den Puffer als auch das Anforderungspaket für den zu verarbeitenden Miniporttreiber enthält. Abhängig von der Anforderung gibt der Treiber angeforderte Informationen in der Struktur zurück, auf die dieser Parameter verweist.

Rückgabewert

MiniportCoOidRequest kann einen der folgenden status-Werte zurückgeben:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	Der Miniporttreiber hat die Daten entweder wie angefordert festgelegt oder abgerufen.
NDIS_STATUS_PENDING	Der Miniporttreiber führt die Anforderung asynchron aus. Nachdem der Miniporttreiber alle Verarbeitungsschritte abgeschlossen hat, muss er die NdisMCoOidRequestComplete-Funktion , um NDIS darüber zu informieren, dass die Anforderung abgeschlossen ist.
NDIS_STATUS_INVALID_OID	Die Anforderung, dass der angegebene OidRequest-Parameter ungültig oder nicht erkannt wurde.
NDIS_STATUS_NOT_SUPPORTED	Die Anforderung, die der angegebene OidRequest-Parameter angegeben hat, wurde erkannt, aber nicht vom Miniporttreiber unterstützt.
NDIS_STATUS_BUFFER_TOO_SHORT	Der vom OidRequest-Parameter bereitgestellte Puffer war zu klein, um die angeforderten Daten zu speichern.
NDIS_STATUS_INVALID_LENGTH	Der Wert, der im InformationBufferLength-Member der NDIS_OID_REQUEST-Struktur bei OidRequest angegeben wurde, ist für den angegebenen OID_XXX-Code falsch.
NDIS_STATUS_INVALID_DATA	Mindestens einer der Parameter, die für die Anforderung bei OidRequest iwas ungültig angegeben wurden.
NDIS_STATUS_NOT_ACCEPTED	Nach dem Aufruf von NDIS MiniportDevicePnPEventNotify-Funktion , um eine überraschende Entfernung anzuzeigen, ruft NDIS die MiniportHaltEx-Funktion des Treibers auf. Wenn der Treiber OID-Anforderungen empfängt, bevor NDIS MiniportHaltEx aufruft, sollte er diese Anforderungen sofort mit dem status Wert NDIS_STATUS_NOT_ACCEPTED abschließen.
NDIS_STATUS_REQUEST_ABORTED	Der Miniporttreiber hat die Verarbeitung der Anforderung beendet. Beispielsweise bezeichnete NDIS miniportResetEx oder MiniportCancelOidRequest-Funktion .

Hinweise

NDIS ruft die MiniportCoOidRequest-Funktion auf, um eine OID-Anforderung zum Abfragen oder Festlegen von Informationen in einem CoNDIS-Miniporttreiber zu verarbeiten.

Um MiniportCoOidRequest zu registrieren, rufen Miniporttreiber die NdisSetOptionalHandlers-Funktion aus der MiniportSetOptions-Funktion auf. In MiniportSetOptions initialisiert der Miniporttreiber eine NDIS_MINIPORT_CO_CHARACTERISTICS Struktur und übergibt sie am OptionalHandlers-Parameter von NdisSetOptionalHandlers.

NDIS ruft die MiniportCoOidRequest-Funktion entweder im eigenen Namen oder im Namen eines gebundenen Protokolltreibers auf, der die NdisCoOidRequest-Funktion aufgerufen hat. Miniport-Treiber sollten die unter OidRequest bereitgestellte Anforderung untersuchen und die angeforderte Aktion ausführen. Weitere Informationen zu den OIDs, die Miniporttreiber verarbeiten, finden Sie unter NDIS-OIDs.

Beachten Sie, dass NDIS den OID-spezifischen Inhalt bei OidRequest nicht überprüft. Daher muss der Treiber selbst diese Inhalte überprüfen. Wenn der Treiber feststellt, dass der festzulegende Wert außerhalb der Grenzen liegt, sollte die Anforderung fehlschlagen und NDIS_STATUS_INVALID_DATA zurückgeben.

Wenn MiniportCoOidRequest NDIS_STATUS_PENDING zurückgibt, kann NDIS MiniportCoOidRequest mit einer anderen Anforderung für den unter MiniportAdapterContext angegebenen Miniportadapter aufrufen, bevor die ausstehende Anforderung abgeschlossen wird. NDIS serialisiert keine verbindungsorientierten OID-Anforderungen.

Beispiele

Um eine MiniportCoOidRequest-Funktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der funktion identifiziert, die Sie definieren. 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 MiniportCoOidRequest-Funktion mit dem Namen "MyCoOidRequest" zu definieren, verwenden Sie den typ MINIPORT_CO_OID_REQUEST , wie in diesem Codebeispiel gezeigt:

MINIPORT_CO_OID_REQUEST MyCoOidRequest;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyCoOidRequest(
    NDIS_HANDLE  MiniportAdapterContext,
    NDIS_HANDLE  MiniportVcContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

Der MINIPORT_CO_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 MINIPORT_CO_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 (include Ndis.h)
IRQL	<= DISPATCH_LEVEL