NdisCoOidRequest, fonction (ndis.h)

Article
02/26/2024

La fonction NdisCoOidRequest transfère une demande aux pilotes CoNDIS ciblés pour interroger ou définir les informations spécifiées par 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 initialement obtenu 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 requête à un client, le gestionnaire d’appels ou MCM a initialement obtenu ce handle en tant que paramètre d’entrée pour sa fonction ProtocolCmOpenAf .

Pour effectuer une requête à partir d’un client ou d’un gestionnaire d’appels autonome vers le pilote miniport sous-jacent, ce paramètre doit être NULL.

[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 au vc. Sinon, si ce paramètre a la valeur NULL, la requête n’est pas propre à VC. Pour toute demande spécifique à vc, l’appelant a obtenu ce handle à l’origine lors de la création de la vc avec la fonction NdisCoCreateVc , ou en tant que paramètre d’entrée pour sa fonction ProtocolCoCreateVc . Pour une requête spécifique à vc qui est dirigée vers le pilote miniport sous-jacent, ce handle identifie le vc, tandis que NdisAfHandle et NdisPartyHandle sont NULL.

[in, optional] NdisPartyHandle

Handle qui identifie le tiers sur un vc multipoint pour lequel l’appelant demande ou définit des informations, si la demande est spécifique à un tiers. Sinon, si ce paramètre a la valeur NULL, la requête n’est pas spécifique à un tiers. Pour toute demande spécifique à une partie, un client a initialement obtenu ce handle à partir d’un appel réussi à la fonction NdisClAddParty , à la fonction NdisClMakeCall ou au gestionnaire d’appels obtenu ce handle en tant que paramètre d’entrée pour sa fonction ProtocolCmAddParty . Si NdisAfHandle a la valeur NULL, NdisPartyHandle a également la valeur NULL.

[in, out] OidRequest

Pointeur vers une structure de 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 retournée

Le pilote cible détermine le code NDIS_STATUS_XXXNdisCoOidRequest retourné, généralement l’une des valeurs suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	L’opération de demande s’est terminée avec succès.
NDIS_STATUS_PENDING	La demande est gérée de manière asynchrone, et NDIS appellera l’appelant Fonction ProtocolCoOidRequestComplete lorsque la demande est terminée.
NDIS_STATUS_INVALID_OID	Le code OID_XXX spécifié dans le membre Oid de la structure NDIS_OID_REQUEST au niveau du paramètre OidRequest n’est pas valide ou n’est pas pris en charge par le pilote sous-jacent.
NDIS_STATUS_INVALID_LENGTH ou NDIS_STATUS_BUFFER_TOO_SHORT	La valeur spécifiée dans le membre InformationBufferLength de la mémoire tampon NDIS_OID_REQUEST-structurée sur OidRequest ne correspond pas aux exigences du code OID_XXX donné. Si la mémoire tampon d’informations est trop petite, le membre BytesNeeded de NDIS_OID_REQUEST contient la valeur correcte pour InformationBufferLength, lorsque NdisCoOidRequest est retourné.
NDIS_STATUS_INVALID_DATA	Les données fournies dans InformationBuffer dans la structure de NDIS_OID_REQUEST donnée ne sont pas valides pour le code OID_XXX donné.
NDIS_STATUS_NOT_SUPPORTED ou NDIS_STATUS_NOT_RECOGNIZED	Le pilote sous-jacent ne prend pas en charge l’opération demandée.
NDIS_STATUS_RESOURCES	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, échouera pour la même raison.
NDIS_STATUS_NOT_ACCEPTED	Le pilote sous-jacent a tenté l’opération demandée, généralement une demande de jeu, 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 le renvoi de cette valeur par NdisCoOidRequest .
NDIS_STATUS_CLOSING ou NDIS_STATUS_CLOSING_INDICATING	Le pilote sous-jacent a échoué l’opération demandée, car une opération de fermeture est en cours.
NDIS_STATUS_RESET_IN_PROGRESS	Le pilote miniport sous-jacent ne peut pas satisfaire la demande pour le moment, 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, échouera pour la même raison.
NDIS_STATUS_FAILURE	Cette valeur est généralement une valeur par défaut non spécifique qui est retournée quand aucune des NDIS_STATUS_XXX plus spécifiques n’a provoqué l’échec de la demande par le pilote sous-jacent.
NDIS_STATUS_REQUEST_ABORTED	Le pilote miniport a cessé de traiter la demande. Par exemple, NDIS a appelé MiniportResetEx d’un pilote miniport 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 sur 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 élevé pendant qu’il traite la requête.

Certaines erreurs retournées par NdisCoOidRequest 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

Autrement dit, un pilote peut modifier le paquet sur OidRequest de manière appropriée pour corriger le code OID_XXX ou la taille ou le contenu de la mémoire tampon dans InformationBuffer et renvoyer le paquet de la demande à NdisCoOidRequest. Le même paquet peut être satisfait lorsque le pilote le resoumet à NdisCoOidRequest si l’appel d’origine indique une réinitialisation en cours ou qu’une pénurie de ressources, qui peut être temporaire, a empêché l’exécution de cette demande.

Selon la valeur du paramètre NdisAfHandle , les clients et les gestionnaires d’appels autonomes appellent NdisCoOidRequest pour communiquer entre eux ou avec le pilote miniport orienté connexion sous-jacent.

Si un pilote transmet NULL pour NdisVcHandle, la requête est globale par nature, que la demande soit dirigée vers le client, le gestionnaire d’appels ou le pilote miniport. Par exemple, si l’appelant fournit une valeur non NULL pour NdisVcHandle, une requête OID OID_GEN_CO_RCV_CRC_ERROR à un pilote miniport orienté connexion sous-jacent retourne le nombre d’erreurs de redondance cyclique case activée (CRC) rencontrées pour un vc particulier. Pour la même requête avec NULL pour NdisVcHandle, le pilote miniport sous-jacent retourne le nombre total d’erreurs CRC qui ont été 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 connexion, tels que ceux qui sont retournés dans une requête OID_GEN_SUPPORTED_LIST , qui est généralement émise lors de l’initialisation après que le pilote de protocole s’est lié au pilote de carte réseau sous-jacent.

Si NdisCoOidRequest retourne NDIS_STATUS_PENDING, la demande est gérée de façon asynchrone et NDIS appelle le pilote Fonction ProtocolCoOidRequestComplete lorsque la demande est terminée. Si NdisCoOidRequest renvoie d’autres status, la demande est terminée lorsque NdisCoOidRequest est retourné, et NDIS n’appelle pas ProtocolCoOidRequestComplete.

Pour plus d’informations sur les ensembles d’OID définis pour être utilisés avec NdisCoOidRequest et NdisOidRequest, consultez NDIS OID OID.

Seuls les clients et les gestionnaires d’appels autonomes, qui sont des pilotes de protocole, peuvent appeler NdisCoOidRequest. Les mcm appellent la fonction NdisMCmOidRequest pour communiquer avec leurs clients.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge dans NDIS 6.0 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	ndis.h (inclure Ndis.h)
Bibliothèque	Ndis.lib
IRQL	<= DISPATCH_LEVEL
Règles de conformité DDI	Irql_Connection_Function(ndis)