PROTOCOL_CO_OID_REQUEST Rückruffunktion (ndis.h)

Artikel
08/07/2023

Die ProtocolCoOidRequest-Funktion verarbeitet OID-Anforderungen, die CoNDIS-Clients oder eigenständige Anruf-Manager durch Aufrufe der NdisCoOidRequest-Funktion initiieren oder die ein MCM-Treiber (Miniport Call Manager) durch Aufrufe der NdisMCmOidRequest-Funktion initiiert.

Hinweis Sie müssen die Funktion mit dem PROTOCOL_CO_OID_REQUEST-Typ deklarieren. Weitere Informationen finden Sie im folgenden Abschnitt Beispiele.

Syntax

PROTOCOL_CO_OID_REQUEST ProtocolCoOidRequest;

NDIS_STATUS ProtocolCoOidRequest(
  [in]      NDIS_HANDLE ProtocolAfContext,
  [in]      NDIS_HANDLE ProtocolVcContext,
  [in]      NDIS_HANDLE ProtocolPartyContext,
  [in, out] PNDIS_OID_REQUEST OidRequest
)
{...}

Parameter

[in] ProtocolAfContext

Ein Handle, das einen Adressfamilienkontextbereich (AF) identifiziert. Wenn es sich bei dem Treiber um einen Client handelt, hat er dieses Handle bereitgestellt, wenn er die NdisClOpenAddressFamilyEx-Funktion , um sich mit dem Anruf-Manager zu verbinden. Wenn der Treiber ein Anruf-Manager ist, hat er dieses Handle über seine ProtocolCmOpenAf-Funktion bereitgestellt.

[in] ProtocolVcContext

Ein Handle, das die virtuelle Verbindung (VC) identifiziert, für die Informationen abgefragt oder festgelegt werden sollen, wenn die Anforderung VC-spezifisch ist. Andernfalls ist dieser Parameter NULL.

[in] ProtocolPartyContext

Ein Handle, das die Partei in einer Multipoint-VC identifiziert, für die Informationen abgefragt oder festgelegt werden sollen, wenn die Anforderung parteispezifisch ist. Andernfalls ist dieser Parameter NULL.

[in, out] OidRequest

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

Rückgabewert

ProtocolCoOidRequest kann eine der folgenden Rückgaben geben:

Rückgabecode	Beschreibung
NDIS_STATUS_SUCCESS	Der Client oder Anrufmanager hat den angeforderten Vorgang ausgeführt.
NDIS_STATUS_PENDING	Der Client oder Anruf-Manager verarbeitet diese Anforderung asynchron und ruft die NdisCoOidRequestComplete-Funktion oder die NdisMCmOidRequestComplete-Funktion , wenn der angeforderte Vorgang abgeschlossen ist.
NDIS_STATUS_INVALID_LENGTH oder NDIS_STATUS_BUFFER_TOO_SHORT	Der Treiber schlägt die Anforderung fehl, da der Aufrufer der NdisCoOidRequest - oder NdisMCmOidRequest-Funktion keinen angemessenen Wert für das InformationBuffer-Element der NDIS_OID_REQUEST-Struktur für die angegebene Anforderung bereitgestellt hat. Der Treiber legt den BytesNeed-Member von NDIS_OID_REQUEST im Puffer am OidRequest-Parameter auf den OID-spezifischen Wert des InformationBufferLength-Members fest, der zum Ausführen des angeforderten Vorgangs erforderlich ist.
NDIS_STATUS_XXX	Der Client oder Der Anruf-Manager hat die Anforderung aus einem treiberbestimmten Grund fehlgeschlagen, z. B. ungültige Eingabedaten, die für einen Satz angegeben wurden.
NDIS_STATUS_NOT_SUPPORTED	Der Client- oder Aufruf-Manager ist bei dieser Anforderung fehlgeschlagen, da er den OID_GEN_CO_XXX-Code im Oid-Member im Puffer bei NdisRequest nicht erkannt hat.

Hinweise

Die ProtocolCoOidRequest-Funktion ist für CoNDIS-Clients, Anruf-Manager und MCMs erforderlich. ProtocolCoOidRequest ähnelt der MiniportCoOidRequest-Funktion des Miniporttreibers .

CoNDIS-Clients und Aufruf-Manager senden Informationen aneinander, indem sie beim Aufrufen der NdisCoOidRequest-Funktion einen Wert ungleich NULL im NdisAfHandle-Parameter angeben. In ähnlicher Weise rufen MCMs NdisMCmOidRequest mit expliziten Werten für NdisAfHandle auf, um Informationen an Clients zu kommunizieren. Solche Aufrufe von NdisCoOidRequest oder NdisMCmOidRequest führen dazu, dass NDIS die ProtocolCoOidRequest-Funktion des Zielclients, Anruf-Managers oder MCM aufruft, die dem angegebenen AF-Handle zugeordnet ist.

Um ProtocolCoOidRequest als Client zu registrieren, initialisiert ein Treiber einen NDIS_CO_CLIENT_OPTIONAL_HANDLERS Struktur und übergibt sie am OptionalHandlers-Parameter der NdisSetOptionalHandlers-Funktion . Um ProtocolCoOidRequest als Anruf-Manager zu registrieren, initialisiert ein Treiber einen NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS Struktur und übergibt sie am Parameter OptionalHandlers .

Wenn die Parameter NdisVcHandle und NdisPartyHandle von NdisCoOidRequest oder NdisMCmOidRequestNULL sind, ist die Anforderung global. Das heißt, ein expliziter Wert für NdisVcHandle oder NdisPartyHandle gibt an, dass ProtocolCoOidRequest die angegebene Anforderung pro VC bzw. pro Partei erfüllen sollte.

Der Puffer am OidRequest-Parameter wurde aus einem nicht ausgestellten Pool zugeordnet und ist daher beim ausgelösten IRQL zugänglich. Der Aufrufer von NdisCoOidRequest(oder NdisMCmOidRequest) muss diesen Puffer und den internen Puffer am InformationBuffer-Member der NDIS_OID_REQUEST Struktur freigeben, auf die OidRequest verweist.

Wenn ProtocolCoOidRequest NDIS_STATUS_PENDING zurückgibt, muss der Treiber anschließend die NdisCoOidRequestComplete-Funktion oder die NdisMCmOidRequestComplete-Funktion für einen MCM-Treiber, wenn der Treiber die Anforderung abgeschlossen hat.

Beispiele

Um eine ProtocolCoOidRequest-Funktion zu definieren, müssen Sie zunächst 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.

Um beispielsweise eine ProtocolCoOidRequest-Funktion mit dem Namen "MyCoOidRequest" zu definieren, verwenden Sie den PROTOCOL_CO_OID_REQUEST-Typ , wie in diesem Codebeispiel gezeigt:

PROTOCOL_CO_OID_REQUEST MyCoOidRequest;

Implementieren Sie dann Ihre Funktion wie folgt:

_Use_decl_annotations_
NDIS_STATUS
 MyCoOidRequest(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

Der PROTOCOL_CO_OID_REQUEST 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 PROTOCOL_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 (einschließlich Ndis.h)
IRQL	<= DISPATCH_LEVEL