PROTOCOL_CO_OID_REQUEST fonction de rappel (ndis.h)
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 MCM (miniport call manager) initie par des appels à la fonction NdisMCmOidRequest .
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 lorsqu’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) sur laquelle interroger ou définir des informations, si la demande est spécifique à VC. Sinon, ce paramètre a la valeur NULL.
[in] ProtocolPartyContext
Handle qui identifie la partie sur un vc multipoint sur lequel interroger ou définir des informations, si la demande est spécifique à une partie. Sinon, ce paramètre a la valeur NULL.
[in, out] OidRequest
Pointeur vers une structure de NDIS_OID_REQUEST qui contient à la fois la mémoire tampon et le paquet de requête que le pilote cible doit gérer. En fonction de la demande, le pilote retourne les informations demandées dans la structure vers laquelle pointe OidRequest .
Valeur retournée
ProtocolCoOidRequest peut retourner l’un des éléments suivants :
| Code de retour | Description |
|---|---|
|
Le client ou le gestionnaire d’appels a effectué l’opération demandée. |
|
Le client, ou le gestionnaire d’appels gère cette demande de manière asynchrone, et il appellera le Fonction NdisCoOidRequestComplete ou Fonction NdisMCmOidRequestComplete lorsque l’opération demandée est terminée. |
|
Le pilote échoue à la demande, car l’appelant de la fonction NdisCoOidRequest ou NdisMCmOidRequest n’a pas fourni une valeur adéquate pour le membre InformationBuffer de la structure NDIS_OID_REQUEST pour la demande donnée. Le pilote définit le membre BytesNeededed de NDIS_OID_REQUEST dans la mémoire tampon au niveau du paramètre OidRequest sur la valeur spécifique à OID du membre InformationBufferLength requis pour effectuer l’opération demandée. |
|
Le client ou le gestionnaire d’appels a échoué à la demande pour une raison déterminée par le pilote, comme des données d’entrée non valides spécifiées pour un ensemble. |
|
Le client ou le gestionnaire d’appels a échoué à cette demande, car il n’a pas reconnu le code OID_GEN_CO_XXX dans le membre Oid dans la mémoire tampon sur NdisRequest. |
Remarques
La fonction ProtocolCoOidRequest est requise pour les clients CoNDIS, les gestionnaires d’appels et les mcms. ProtocolCoOidRequest est similaire à la fonction MiniportCoOidRequest du pilote miniport .
Les clients CoNDIS et les gestionnaires d’appels s’envoient des informations en spécifiant une valeur non NULL dans le paramètre NdisAfHandle lorsqu’ils appellent la fonction NdisCoOidRequest . De même, les MCM appellent la requête NdisMCmOidRequest avec des valeurs explicites pour NdisAfHandle afin de communiquer des informations aux clients. De tels appels à NdisCoOidRequest ou NdisMCmOidRequest entraînent l’appel de 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 demande est de nature globale. Autrement dit, une valeur explicite pour NdisVcHandle ou NdisPartyHandle indique que ProtocolCoOidRequest doit répondre à la demande donnée par vc ou par partie, respectivement.
La mémoire tampon au niveau du paramètre OidRequest a été allouée à partir d’un pool non paginé et est donc accessible au niveau de l’IRQL levé. L’appelant de NdisCoOidRequest(ou NdisMCmOidRequest) doit libérer cette mémoire tampon et la mémoire tampon interne au niveau du membre InformationBuffer de la structure NDIS_OID_REQUEST vers laquelle pointe OidRequest .
Si ProtocolCoOidRequest retourne NDIS_STATUS_PENDING, le pilote doit ensuite appeler le NdisCoOidRequestComplete , ou la fonction Fonction NdisMCmOidRequestComplete pour un pilote MCM, lorsque le pilote termine la demande.
Exemples
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 fonction permet à l’analyse du code pour les pilotes, le vérificateur de pilotes statique (SDV) et d’autres outils de vérification de trouver les erreurs, et il s’agit d’une exigence pour l’écriture de 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 lors de l’exécution des 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 Annotating Function Behavior.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Pris en charge dans NDIS 6.0 et versions ultérieures. |
| Plateforme cible | Windows |
| En-tête | ndis.h (inclure Ndis.h) |
| IRQL | <= DISPATCH_LEVEL |