NdisCoOidRequest, fonction (ndis.h)
La fonction NdisCoOidRequest transfère une requête aux pilotes CoNDIS ciblés pour interroger ou définir des informations spécifiées par l’OID du pilote cible.
Syntaxe
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
);
Paramètres
[in] NdisBindingHandle
Handle retourné par la fonction NdisOpenAdapterEx qui identifie l’adaptateur cible pour la liaison.
[in, optional] NdisAfHandle
Handle qui identifie la famille d’adresses (AF) partagée entre le client, le gestionnaire d’appels et NDIS. Ce handle a été obtenu comme suit :
- Si l’appelant est un client qui effectue une demande au gestionnaire d’appels, le client a obtenu à l’origine ce handle à partir d’un appel réussi au fonction NdisClOpenAddressFamilyEx.
- Si l’appelant est un gestionnaire d’appels autonome ou un gestionnaire d’appels miniport (MCM) qui effectue une demande à un client, le gestionnaire d’appels ou MCM a obtenu ce handle à l’origine en tant que paramètre d’entrée pour sa fonction ProtocolCmOpenAf.
[in, optional] NdisVcHandle
Handle qui identifie la connexion virtuelle (VC) pour laquelle l’appelant demande ou définit des informations, si la demande est spécifique à VC. Sinon, si ce paramètre est NULL, la requête n’est pas spécifique à VC. Pour toute requête spécifique à la vc, l’appelant a obtenu à l’origine ce handle lors de la création de la vc avec la fonction NdisCoCreateVc, ou en tant que paramètre d’entrée à sa fonction ProtocolCoCreateVc. Pour une requête spécifique à vc qui est dirigée vers le pilote miniport sous-jacent, ce handle identifie la vc, tandis que NdisAfHandle et NdisPartyHandle sont NULL.
[in, optional] NdisPartyHandle
Handle qui identifie la partie sur un vc multipoint pour lequel l’appelant demande ou définit des informations, si la demande est spécifique à une partie. Sinon, si ce paramètre est NULL, la requête n’est pas spécifique à la partie. Pour toute requête spécifique à une partie, un client a obtenu à l’origine ce handle à partir d’un appel réussi à la fonction NdisClAddParty ou à la fonction NdisClMakeCall ou au gestionnaire d’appels a obtenu ce handle en tant que paramètre d’entrée à sa fonction ProtocolCmAddParty. Si NdisAfHandle est NULL, NdisPartyHandle est également NULL.
[in, out] OidRequest
Pointeur vers une structure NDIS_OID_REQUEST qui spécifie l’opération demandée avec un code OID_XXX donné pour interroger ou définir des informations.
Valeur de retour
Le pilote cible détermine quel code NDIS_STATUS_XXXNdisCoOidRe quest retourne, généralement l’une des valeurs suivantes :
| Retourner le code | Description |
|---|---|
|
L’opération de demande s’est terminée avec succès. |
|
La requête est gérée de façon asynchrone et NDIS appellera l’appelant. ProtocolCoOidRequestComplete fonction lorsque la requête est terminée. |
|
Le code OID_XXX spécifié dans le membre Oid de la structure NDIS_OID_REQUEST au paramètre OidRequest n’est pas valide ou non pris en charge par le pilote sous-jacent. |
|
La valeur spécifiée dans le InformationBufferLength membre de la mémoire tampon structurée NDIS_OID_REQUEST à OidRequest ne correspond pas aux exigences du codeXXX OID_ donné. Si la mémoire tampon d’informations est trop petite, le membre BytesNeededed de NDIS_OID_REQUEST contient la valeur correcte pour InformationBufferLength, lorsque NdisCoOidRequest retourne. |
|
Les données fournies au InformationBuffer dans la structure de NDIS_OID_REQUEST donnée ne sont pas valides pour le codeXXX OID_ donné. |
|
Le pilote sous-jacent ne prend pas en charge l’opération demandée. |
|
La demande n’a pas pu être satisfaite en raison d’une pénurie de ressources. En règle générale, cette valeur de retour indique qu’une tentative d’allocation de mémoire a échoué, mais elle n’indique pas nécessairement que la même demande, si elle est envoyée ultérieurement, échoue pour la même raison. |
|
Le pilote sous-jacent a tenté l’opération demandée, généralement une demande définie, mais l’opération a échoué. Par exemple, une tentative de définition d’un trop grand nombre d’adresses de multidiffusion peut entraîner NdisCoOidRequest retourner cette valeur. |
|
Le pilote sous-jacent a échoué l’opération demandée, car une opération de fermeture est en cours. |
|
Le pilote miniport sous-jacent ne peut pas satisfaire la requête pour l’instant, car il réinitialise actuellement la carte réseau affectée. La fonction ProtocolStatusEx de l’appelant a été ou sera appelée avec NDIS_STATUS_RESET_START pour indiquer qu’une réinitialisation est en cours. Cette valeur de retour n’indique pas nécessairement que la même demande, si elle est envoyée ultérieurement, échoue pour la même raison. |
|
Cette valeur est généralement une valeur par défaut non spécifique retournée lorsqu’aucune des NDIS_STATUS_XXX plus spécifiques n’a provoqué l’échec de la requête par le pilote sous-jacent. |
|
Le pilote miniport a arrêté le traitement de la requête. Par exemple, NDIS a appelé un miniport driver sous-jacent ou Fonction MiniportCancelOidRequest. |
Remarques
Les clients CoNDIS et les gestionnaires d’appels autonomes peuvent appeler la fonction NdisCoOidRequest pour envoyer une requête OID pour interroger ou définir des informations spécifiées par OID dans un pilote cible. Le pilote cible peut être un autre pilote de protocole CoNDIS ou un pilote sous-jacent.
L’appelant de NdisCoOidRequest doit allouer suffisamment de mémoire pour contenir la mémoire tampon d’informations associée à l’OID spécifié. L’appelant doit également allouer et configurer la mémoire tampon à OidRequest avant d’appeler NdisCoOidRequest. Les deux mémoires tampons doivent être allouées à partir d’un pool non paginé, car le pilote cible peut s’exécuter à l’irQL déclenché pendant qu’il traite la requête.
Certaines erreurs qui NdisCoOidRequest retournent sont récupérables, notamment les suivantes :
- 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
Selon la valeur du paramètre NdisAfHandle, les clients et les gestionnaires d’appels autonomes appellent NdisCoOidRequest communiquer entre eux ou avec le pilote miniport orienté connexion sous-jacent.
Si un pilote passe NULL pour NdisVcHandle, la requête est globale, que la requête soit dirigée vers le client, le gestionnaire d’appels ou le pilote miniport. Par exemple, si l’appelant fournit une valeur deNULL non- pour NdisVcHandle, une demande OID OID_GEN_CO_RCV_CRC_ERROR à un pilote miniport orienté connexion sous-jacent retourne le nombre d’erreurs de vérification de redondance cyclique (CRC) qui ont été rencontrées pour une vc particulière. Pour la même requête avec NULL pour NdisVcHandle, le pilote miniport sous-jacent retourne le nombre total d’erreurs CRC rencontrées pour toutes les machines virtuelles.
Les clients et les gestionnaires d’appels autonomes doivent appeler la fonction NdisOidRequest pour tous les OID qui ne sont pas orientés vers la connexion, tels que ceux retournés dans une requête OID_GEN_SUPPORTED_LIST, qui est généralement émise lors de l’initialisation une fois que le pilote de protocole s’est lié au pilote de carte réseau sous-jacent.
Si NdisCoOidRequest retourne NDIS_STATUS_PENDING, la requête est gérée de manière asynchrone et NDIS appellera le pilote de manière asynchrone. ProtocolCoOidRequestComplete fonction lorsque la requête est terminée. Si NdisCoOidRequest retourne un autre état, la requête est terminée lorsque NdisCoOidRequest retourne, et NDIS n’appelle pas ProtocolCoOidRequestComplete.
Pour plus d’informations sur les ensembles d’OID définis à utiliser avec NdisCoOidRequest et NdisOidRequest, consultez NDIS OIDs.
Seuls les clients et les gestionnaires d’appels autonomes, qui sont des pilotes de protocole, peuvent appeler NdisCoOidRequest. Les mcms appellent la fonction NdisMCmOidRequest pour communiquer avec leurs clients.