NdisCoOidRequest-Funktion (ndis.h)

Artikel
02/07/2025

Die NdisCoOidRequest Funktion leitet eine Anforderung an gezielte CoNDIS-Treiber weiter, um OID-angegebene Informationen des Zieltreibers abzufragen oder festzulegen.

Syntax

NDIS_STATUS NdisCoOidRequest(
  [in]           NDIS_HANDLE       NdisBindingHandle,
  [in, optional] NDIS_HANDLE       NdisAfHandle,
  [in, optional] NDIS_HANDLE       NdisVcHandle,
  [in, optional] NDIS_HANDLE       NdisPartyHandle,
  [in, out]      PNDIS_OID_REQUEST OidRequest
);

Parameter

[in] NdisBindingHandle

Ein Handle, das die NdisOpenAdapterEx-Funktion zurückgegeben hat, die den Zieladapter für die Bindung identifiziert.

[in, optional] NdisAfHandle

Ein Handle, das die Adressfamilie (AF) identifiziert, die zwischen dem Client, dem Anrufmanager und NDIS geteilt wird. Dieses Handle wurde wie folgt abgerufen:

Wenn der Anrufer ein Client ist, der eine Anforderung an den Anrufmanager vornimmt, hat der Client dieses Handle ursprünglich von einem erfolgreichen Anruf an den Anruf abgerufen. NdisClOpenAddressFamilyEx Funktion.
Wenn es sich bei dem Anrufer um einen eigenständigen Anruf-Manager oder einen Miniport-Anruf-Manager (MCM) handelt, der eine Anforderung an einen Client vornimmt, hat der Anrufmanager oder MCM dieses Handle ursprünglich als Eingabeparameter für seine ProtocolCmOpenAf--Funktion abgerufen.

Um eine Anforderung von einem Client oder einem eigenständigen Aufruf-Manager an den zugrunde liegenden Miniporttreiber zu senden, muss dieser Parameter NULL-sein.

[in, optional] NdisVcHandle

Ein Handle, das die virtuelle Verbindung (VC) identifiziert, für die der Aufrufer Informationen anfordert oder festlegt, wenn die Anforderung VC-spezifisch ist. Andernfalls ist dieser Parameter NULL, ist die Anforderung nicht VC-spezifisch. Bei jeder VC-spezifischen Anforderung hat der Aufrufer dieses Handle ursprünglich abgerufen, entweder beim Erstellen des VC mit der NdisCoCreateVc--Funktion oder als Eingabeparameter für die ProtocolCoCreateVc--Funktion. Bei einer VC-spezifischen Anforderung, die an den zugrunde liegenden Miniporttreiber weitergeleitet wird, identifiziert dieses Handle den VC, während NdisAfHandle- und NdisPartyHandle-NULL-sind.

[in, optional] NdisPartyHandle

Ein Handle, das die Partei auf einem Multipoint VC identifiziert, für die der Anrufer Informationen anfordert oder festlegt, wenn die Anforderung parteispezifisch ist. Andernfalls ist dieser Parameter NULL, ist die Anforderung nicht parteispezifisch. Für jede parteispezifische Anforderung hat ein Client dieses Handle ursprünglich von einem erfolgreichen Aufruf der NdisClAddParty Funktion oder der NdisClMakeCall-Funktion oder vom Aufruf-Manager als Eingabeparameter für die ProtocolCmAddParty-Funktion abgerufen. Wenn NdisAfHandle-NULL-ist, ist NdisPartyHandle auch NULL-.

[in, out] OidRequest

Ein Zeiger auf eine NDIS_OID_REQUEST Struktur, die den Vorgang angibt, der mit einem bestimmten OID_XXX Code zum Abfragen oder Festlegen von Informationen angefordert wird.

Rückgabewert

Der Zieltreiber bestimmt, welcher NDIS_STATUS_XXX Code NdisCoOidRequest zurückgibt, in der Regel eines der folgenden Werte:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	Der Anforderungsvorgang wurde erfolgreich abgeschlossen.
NDIS_STATUS_PENDING	Die Anforderung wird asynchron verarbeitet, und NDIS ruft die Aufrufer auf. ProtocolCoOidRequestComplete Funktion, wenn die Anforderung abgeschlossen ist.
NDIS_STATUS_INVALID_OID	Der OID_XXX- Code, der im Oid- Member der NDIS_OID_REQUEST Struktur an der OidRequest Parameter angegeben wurde, ist ungültig oder wird vom zugrunde liegenden Treiber nicht unterstützt.
NDIS_STATUS_INVALID_LENGTH oder NDIS_STATUS_BUFFER_TOO_SHORT	Der wert, der im InformationBufferLength Member des NDIS_OID_REQUEST strukturierten Puffers bei OidRequest- angegeben wurde, entspricht nicht den Anforderungen für den angegebenen OID_XXX- Code. Wenn der Informationspuffer zu klein ist, enthält das ByteNeeded- element von NDIS_OID_REQUEST den richtigen Wert für InformationBufferLength, wenn NdisCoOidRequest zurückgibt.
NDIS_STATUS_INVALID_DATA	Die bei InformationBuffer in der angegebenen NDIS_OID_REQUEST Struktur bereitgestellten Daten sind für den angegebenen OID_XXX- Code ungültig.
NDIS_STATUS_NOT_SUPPORTED oder NDIS_STATUS_NOT_RECOGNIZED	Der zugrunde liegende Treiber unterstützt den angeforderten Vorgang nicht.
NDIS_STATUS_RESOURCES	Die Anforderung konnte aufgrund eines Ressourcenmangels nicht erfüllt werden. Normalerweise gibt dieser Rückgabewert an, dass ein Versuch, Arbeitsspeicher zuzuweisen, nicht erfolgreich war, aber nicht notwendigerweise darauf hinweist, dass dieselbe Anforderung, wenn sie später übermittelt wird, aus demselben Grund fehlschlägt.
NDIS_STATUS_NOT_ACCEPTED	Der zugrunde liegende Treiber hat den angeforderten Vorgang versucht, in der Regel eine festgelegte Anforderung, aber der Vorgang ist fehlgeschlagen. Ein Versuch, zu viele Multicastadressen festzulegen, kann z. B. dazu führen, dass NdisCoOidRequest diesen Wert zurückgeben.
NDIS_STATUS_CLOSING oder NDIS_STATUS_CLOSING_INDICATING	Der zugrunde liegende Treiber hat den angeforderten Vorgang fehlgeschlagen, da ein Abschlussvorgang ausgeführt wird.
NDIS_STATUS_RESET_IN_PROGRESS	Der zugrunde liegende Miniporttreiber kann die Anforderung zu diesem Zeitpunkt nicht erfüllen, da die betroffene NIC derzeit zurückgesetzt wird. Die ProtocolStatusEx-Funktion des Aufrufers wurde oder wird mit NDIS_STATUS_RESET_START aufgerufen, um anzugeben, dass eine Zurücksetzung ausgeführt wird. Dieser Rückgabewert gibt nicht unbedingt an, dass die gleiche Anforderung, wenn sie später übermittelt wird, aus demselben Grund fehlschlägt.
NDIS_STATUS_FAILURE	Dieser Wert ist in der Regel ein nicht spezifischer Standardwert, der zurückgegeben wird, wenn keiner der spezifischeren NDIS_STATUS_XXX- verursacht hat, dass der zugrunde liegende Treiber die Anforderung fehlschlägt.
NDIS_STATUS_REQUEST_ABORTED	Der Miniporttreiber hat die Verarbeitung der Anforderung beendet. Beispielsweise hat NDIS die MiniportResetEx- oder MiniportCancelOidRequest Funktion.

Bemerkungen

CoNDIS-Clients und eigenständige Anrufmanager können die NdisCoOidRequest Funktion aufrufen, um eine OID-Anforderung an abfragen oder OID-angegebene Informationen in einem Zieltreiber festzulegen. Der Zieltreiber kann ein anderer CoNDIS-Protokolltreiber oder ein zugrunde liegender Treiber sein.

Der Aufrufer von NdisCoOidRequest muss genügend Arbeitsspeicher zuweisen, um den Informationspuffer zu speichern, der dem angegebenen OID zugeordnet ist. Der Aufrufer muss den Puffer auch bei OidRequest- zuordnen und einrichten, bevor er NdisCoOidRequest-aufruft. Beide Puffer müssen aus einem nicht ausgelagerten Pool zugewiesen werden, da der Zieltreiber bei ausgelösten IRQL-Vorgängen ausgeführt werden kann, während die Anforderung verarbeitet wird.

Einige Fehler, die NdisCoOidRequest- zurückgegeben werden, können wiederhergestellt werden, einschließlich der folgenden:

NDIS_STATUS_INVALID_OID
NDIS_STATUS_INVALID_LENGTH
NDIS_STATUS_BUFFER_TOO_SHORT
NDIS_STATUS_INVALID_DATA
NDIS_STATUS_RESOURCES
NDIS_STATUS_RESET_IN_PROGRESS

Das heißt, ein Treiber kann das Paket bei OidRequest entsprechend ändern, um den OID_XXX- code oder die Größe oder den Inhalt des Puffers bei InformationBuffer- zu korrigieren und das Anforderungspaket erneut an NdisCoOidRequestzu übermitteln. Dasselbe Paket kann erfüllt sein, wenn der Treiber es erneut an NdisCoOidRequest, wenn der ursprüngliche Aufruf eine Zurücksetzung anzeigte oder dass ein Ressourcenmangel, der vorübergehend sein könnte, verhinderte, dass diese Anforderung ausgeführt wird.

Abhängig vom Wert des NdisAfHandle Parameter rufen Clients und eigenständige Anrufmanager NdisCoOidRequest auf, um miteinander oder mit dem zugrunde liegenden verbindungsorientierten Miniporttreiber zu kommunizieren.

Wenn ein Treiber NULL- für NdisVcHandle-übergibt, ist die Anforderung global, unabhängig davon, ob die Anforderung an den Client, den Anruf-Manager oder den Miniporttreiber weitergeleitet wird. Wenn der Aufrufer z. B. einen Nicht-NULL- Wert für NdisVcHandlebereitstellt, gibt eine OID_GEN_CO_RCV_CRC_ERROR OID-Anforderung an einen zugrunde liegenden verbindungsorientierten Miniporttreiber die Anzahl von zyklischen Redundanzüberprüfungsfehlern (CRC) zurück, die für eine bestimmte VC aufgetreten sind. Für dieselbe Anforderung mit NULL- für NdisVcHandlegibt der zugrunde liegende Miniporttreiber die Gesamtanzahl der CRC-Fehler zurück, die für alle VCs aufgetreten sind.

Clients und eigenständige Anrufmanager sollten die NdisOidRequest Funktion für alle OIDs aufrufen, die nicht verbindungsorientiert sind, z. B. diejenigen, die in einer OID_GEN_SUPPORTED_LIST-Abfrage zurückgegeben werden, die häufig während der Initialisierung ausgegeben werden, nachdem sich der Protokolltreiber an den zugrunde liegenden NIC-Treiber gebunden hat.

Wenn NdisCoOidRequest NDIS_STATUS_PENDING zurückgibt, wird die Anforderung asynchron behandelt, und NDIS ruft die Treiber auf. ProtocolCoOidRequestComplete Funktion, wenn die Anforderung abgeschlossen ist. Wenn NdisCoOidRequest einen anderen Status zurückgibt, wird die Anforderung abgeschlossen, wenn NdisCoOidRequest- zurückgegeben wird, und NDIS ruft ProtocolCoOidRequestCompletenicht auf.

Weitere Informationen zu den Gruppen von OIDs, die für die Verwendung mit NdisCoOidRequest und NdisOidRequest-definiert sind, finden Sie unter NDIS OIDs.

Nur Clients und eigenständige Anrufmanager, die Protokolltreiber sind, können NdisCoOidRequest-aufrufen. MCMs rufen die NdisMCmOidRequest Funktion auf, um mit ihren Clients zu kommunizieren.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Unterstützt in NDIS 6.0 und höher.
Zielplattform-	Desktop
Header-	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL-	<= DISPATCH_LEVEL
DDI-Complianceregeln	Irql_Connection_Function(ndis)