PROTOCOL_CO_OID_REQUEST fonction de rappel (ndis.h)

Article
02/07/2025

La fonction ProtocolCoOidRequest gère les demandes OID que les clients CoNDIS ou les gestionnaires d’appels autonomes lancent par des appels à la fonction NdisCoOidRequest ou qu’un pilote de gestionnaire d’appels miniport (MCM) lance par des appels à la fonction NdisMCmOidRequest.

Remarque Vous devez déclarer la fonction à l’aide du type PROTOCOL_CO_OID_REQUEST. Pour plus d’informations, consultez la section Exemples suivants.

Syntaxe

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
)
{...}

Paramètres

[in] ProtocolAfContext

Handle qui identifie une zone de contexte de famille d’adresses (AF). Si le pilote est un client, il a fourni ce handle quand il a appelé le fonction NdisClOpenAddressFamilyEx pour se connecter au gestionnaire d’appels. Si le pilote est un gestionnaire d’appels, il a fourni ce handle à partir de sa fonction ProtocolCmOpenAf.

[in] ProtocolVcContext

Handle qui identifie la connexion virtuelle (VC) pour interroger ou définir des informations sur, si la requête est spécifique à VC. Sinon, ce paramètre est NULL .

[in] ProtocolPartyContext

Handle qui identifie la partie sur un vc multipoint pour interroger ou définir des informations sur, si la demande est spécifique à une partie. Sinon, ce paramètre est NULL .

[in, out] OidRequest

Pointeur vers une structure NDIS_OID_REQUEST qui contient à la fois la mémoire tampon et le paquet de requête pour que le pilote cible gère. Selon la requête, le pilote retourne les informations demandées dans la structure vers laquelle OidRequest pointe.

Valeur de retour

ProtocolCoOidRequest peut retourner l’une des options suivantes :

Retourner le code	Description
NDIS_STATUS_SUCCESS	Le client ou le gestionnaire d’appels a effectué l’opération demandée.
NDIS_STATUS_PENDING	Le client, ou le gestionnaire d’appels gère cette requête de manière asynchrone, et il appellera le NdisCoOidRequestComplete fonction ou fonction NdisMCmOidRequestComplete une fois l’opération demandée terminée.
NDIS_STATUS_INVALID_LENGTH ou NDIS_STATUS_BUFFER_TOO_SHORT	Le pilote échoue à la demande, car l’appelant de la fonction NdisCoOidRequest ou NdisMCmOidRequest n’a pas fourni de valeur adéquate pour le membre InformationBuffer de la structure NDIS_OID_REQUEST pour la demande donnée. Le pilote définit le membre de NDIS_OID_REQUEST dans la mémoire tampon au paramètre OidRequest à la valeur spécifique à l’OID du membre InformationBufferLength requis pour effectuer l’opération demandée.
NDIS_STATUS_XXX	Le client ou le gestionnaire d’appels a échoué à la demande d’une raison déterminée par le pilote, telle que les données d’entrée non valides spécifiées pour un ensemble.
NDIS_STATUS_NOT_SUPPORTED	Le client ou le gestionnaire d’appels a échoué, car il n’a pas reconnu le codeXXX OID_GEN_CO_ dans le membre Oid dans la mémoire tampon à NdisRequest.

Remarques

La fonction ProtocolCoOidRequest est requise pour les clients CoNDIS, les gestionnaires d’appels et les mcMs. ProtocolCoOidRequest est similaire à la fonction miniport driver MiniportCoOidRequest.

Les clients coNDIS et les gestionnaires d’appels envoient des informations entre eux en spécifiant une valeurNULL non dans le paramètre NdisAfHandle lorsqu’ils appellent la fonction NdisCoOidRequest. De même, les mcms appellent le NdisMCmOidRequest avec des valeurs explicites pour NdisAfHandle communiquer des informations aux clients. Ces appels à NdisCoOidRequest ou NdisMCmOidRequest entraînent l’appel de NDIS à la fonction ProtocolCoOidRequest du client ciblé, du gestionnaire d’appels ou du MCM associé au handle AF spécifié.

Pour inscrire ProtocolCoOidRequest en tant que client, un pilote initialise un NDIS_CO_CLIENT_OPTIONAL_HANDLERS structure et la transmet au paramètre OptionalHandlers de la fonction NdisSetOptionalHandlers. Pour inscrire ProtocolCoOidRequest en tant que gestionnaire d’appels, un pilote initialise un NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS structure et la transmet au paramètre OptionalHandlers.

Si les paramètres NdisVcHandle et NdisPartyHandle de NdisCoOidRequest ou NdisMCmOidRequest sont NULL, la requête est globale dans la nature. Autrement dit, une valeur explicite pour NdisVcHandle ou NdisPartyHandle indique que ProtocolCoOidRequest doit satisfaire la demande donnée sur une base par VC ou par partie, respectivement.

La mémoire tampon au niveau de la paramètre OidRequest a été allouée à partir du pool non paginé et est, par conséquent, accessible à l’irQL déclenché. L’appelant de NdisCoOidRequest(ou NdisMCmOidRequest) doit libérer cette mémoire tampon et la mémoire tampon interne au membre de la structure NDIS_OID_REQUEST InformationBuffer OidRe quest pointe vers.

Si ProtocolCoOidRequest retourne NDIS_STATUS_PENDING, le pilote doit ensuite appeler le fonction NdisCoOidRequestComplete, ou NdisMCmOidRequestComplete fonction pour un pilote MCM lorsque le pilote termine la requête.

exemples de

Pour définir une fonction ProtocolCoOidRequest, vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction que vous définissez. Windows fournit un ensemble de types de fonctions pour les pilotes. La déclaration d’une fonction à l’aide des types de fonctions permet d'Analyse du code pour les pilotes, de vérificateur de pilotes statiques (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une fonction ProtocolCoOidRequest nommée « MyCoOidRequest », utilisez le type PROTOCOL_CO_OID_REQUEST comme indiqué dans cet exemple de code :

PROTOCOL_CO_OID_REQUEST MyCoOidRequest;

Ensuite, implémentez votre fonction comme suit :

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

Le type de fonction PROTOCOL_CO_OID_REQUEST est défini dans le fichier d’en-tête Ndis.h. Pour identifier plus précisément les erreurs lorsque vous exécutez les outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction PROTOCOL_CO_OID_REQUEST dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes NDIS.

Pour plus d’informations sur Use_decl_annotations, consultez annoter le comportement de la fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Prise en charge dans NDIS 6.0 et versions ultérieures.
plateforme cible	Windows
d’en-tête	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL