NdisCoOidRequest-Funktion (ndis.h)

Artikel
02/29/2024

Die NdisCoOidRequest-Funktion leitet eine Anforderung an zielorientierte 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 Von der NdisOpenAdapterEx-Funktion zurückgegebenes Handle, das den Zieladapter für die Bindung identifiziert.

[in, optional] NdisAfHandle

Ein Handle, das die Adressfamilie (AF) identifiziert, die für den Client, den Anruf-Manager und die NDIS freigegeben wird. Dieses Handle wurde wie folgt abgerufen:

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

Um eine Anforderung von einem Client oder einem eigenständigen Anruf-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 die Anforderung nicht VC-spezifisch, wenn dieser Parameter NULL ist. Für jede VC-spezifische Anforderung hat der Aufrufer dieses Handle ursprünglich abgerufen, als er die VC mit der NdisCoCreateVc-Funktion erstellt hat, oder als Eingabeparameter für seine ProtocolCoCreateVc-Funktion . Bei einer VC-spezifischen Anforderung, die an den zugrunde liegenden Miniporttreiber weitergeleitet wird, identifiziert dieses Handle den VC, während NdisAfHandle und NdisPartyHandleNULL sind.

[in, optional] NdisPartyHandle

Ein Handle, das die Partei auf einer Multipoint-VC identifiziert, für die der Aufrufer Informationen anfordert oder festlegt, wenn die Anforderung parteispezifisch ist. Andernfalls ist die Anforderung nicht parteispezifisch, wenn dieser Parameter NULL ist. 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 seine ProtocolCmAddParty-Funktion abgerufen. Wenn NdisAfHandleNULL ist, ist NdisPartyHandle ebenfalls NULL.

[in, out] OidRequest

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

Rückgabewert

Der Zieltreiber bestimmt, welchen NDIS_STATUS_XXX-CodeNdisCoOidRequest zurückgibt, in der Regel einer der folgenden Werte:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	Der Anforderungsvorgang wurde erfolgreich abgeschlossen.
NDIS_STATUS_PENDING	Die Anforderung wird asynchron behandelt, und NDIS ruft den 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 am 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 BytesNeeded-Element von NDIS_OID_REQUEST den richtigen Wert für InformationBufferLength, wenn NdisCoOidRequest zurückgibt.
NDIS_STATUS_INVALID_DATA	Die unter 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. In der Regel gibt dieser Rückgabewert an, dass ein Versuch, Arbeitsspeicher zuzuweisen, fehlgeschlagen ist, aber nicht notwendigerweise, 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. Beispielsweise kann ein Versuch, zu viele Multicastadressen festzulegen, dazu führen, dass NdisCoOidRequest diesen Wert zurückgibt.
NDIS_STATUS_CLOSING oder NDIS_STATUS_CLOSING_INDICATING	Beim zugrunde liegenden Treiber ist der angeforderte Vorgang fehlgeschlagen, da ein Schließenvorgang ausgeführt wird.
NDIS_STATUS_RESET_IN_PROGRESS	Der zugrunde liegende Miniporttreiber kann die Anforderung derzeit 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 ein Zurücksetzen ausgeführt wird. Dieser Rückgabewert weist nicht unbedingt darauf hin, dass dieselbe Anforderung, wenn sie später übermittelt wird, aus demselben Grund fehlschlägt.
NDIS_STATUS_FAILURE	Dieser Wert ist in der Regel ein unspezifischer 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 bezeichnete NDIS miniportResetEx eines zugrunde liegenden Miniporttreibers oder MiniportCancelOidRequest-Funktion .

Hinweise

CoNDIS-Clients und eigenständige Anrufmanager können die NdisCoOidRequest-Funktion aufrufen, um eine OID-Anforderung zum Abfragen oder Festlegen von OID-angegebenen Informationen in einem Zieltreiber zu senden. 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 der angegebenen OID zugeordnet ist. Der Aufrufer muss auch den Puffer bei OidRequest zuordnen und einrichten, bevor er NdisCoOidRequest aufruft. Beide Puffer müssen aus einem nicht ausgestellten Pool zugeordnet werden, da der Zieltreiber bei ausgelöstem IRQL ausgeführt werden kann, während er die Anforderung verarbeitet.

Einige Fehler, die NdisCoOidRequest zurückgibt, können wie folgt wiederhergestellt werden:

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 in NdisCoOidRequest zu übermitteln. Dasselbe Paket kann erfüllt sein, wenn der Treiber es erneut an NdisCoOidRequest übermittelt, wenn der ursprüngliche Aufruf eine laufende Zurücksetzung anzeigt oder dass eine Ressourcenknappheit, die möglicherweise vorübergehend sein kann, die Ausführung dieser Anforderung verhindert hat.

Abhängig vom Wert des NdisAfHandle-Parameters 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 beispielsweise einen Nicht-NULL-Wert für NdisVcHandle bereitstellt, gibt eine OID_GEN_CO_RCV_CRC_ERROR OID-Anforderung an einen zugrunde liegenden verbindungsorientierten Miniporttreiber die Anzahl der Fehler der zyklischen Redundanzprüfung (CRC) zurück, die für eine bestimmte VC aufgetreten sind. Für dieselbe Anforderung mit NULL für NdisVcHandle gibt der zugrunde liegende Miniporttreiber die Gesamtzahl der CRC-Fehler zurück, die für alle VCs aufgetreten sind.

Clients und eigenständige Anruf-Manager sollten die NdisOidRequest-Funktion für alle nicht verbindungsorientierten OIDs aufrufen, z. B. für diejenigen, die in einer OID_GEN_SUPPORTED_LIST Abfrage zurückgegeben werden, die häufig während der Initialisierung ausgegeben wird, 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 den Treiber auf. ProtocolCoOidRequestComplete-Funktion , wenn die Anforderung abgeschlossen ist. Wenn NdisCoOidRequest eine andere status zurückgibt, ist die Anforderung abgeschlossen, wenn NdisCoOidRequest zurückgibt, und NDIS ruft ProtocolCoOidRequestComplete nicht 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 Anruf-Manager, bei denen es sich um Protokolltreiber handelt, können NdisCoOidRequest aufrufen. MCMs rufen die NdisMCmOidRequest-Funktion auf, um mit ihren Clients zu kommunizieren.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt in NDIS 6.0 und höher.
Zielplattform	Desktop
Kopfzeile	ndis.h (einschließlich Ndis.h)
Bibliothek	Ndis.lib
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	Irql_Connection_Function(ndis)