PROTOCOL_CO_OID_REQUEST_COMPLETE fonction de rappel (ndis.h)

Article
08/07/2023

La fonction ProtocolCoOidRequestComplete termine le traitement d’une requête OID CoNDIS asynchrone.

Note Vous devez déclarer la fonction à l’aide du type PROTOCOL_CO_OID_REQUEST_COMPLETE . Pour plus d’informations, consultez la section Exemples suivante.

Syntaxe

PROTOCOL_CO_OID_REQUEST_COMPLETE ProtocolCoOidRequestComplete;

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

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 ou un gestionnaire d’appels miniport (MCM), il a fourni ce handle à partir de sa fonction ProtocolCmOpenAf .

[in] ProtocolVcContext

Handle qui identifie la connexion virtuelle active (VC) pour laquelle le pilote a demandé ou pour laquelle il a défini des informations, si la demande était spécifique à VC. Sinon, ce paramètre a la valeur NULL.

[in] ProtocolPartyContext

Handle qui identifie la partie sur un vc multipoint pour laquelle le pilote a demandé ou pour laquelle il a défini des informations, si la demande est spécifique à une partie. Sinon, ce paramètre a la valeur NULL.

[in, out] OidRequest

Pointeur vers la structure NDIS_OID_REQUEST fournie par le pilote qui a été passée à la fonction NdisCoOidRequest ou NdisMCmOidRequest .

[in] Status

Status finale de la demande. Le pilote cible ou NDIS détermine cette status finale. Ce paramètre détermine ce que ProtocolCoOidRequestComplete fait avec les informations dans OidRequest.

Valeur de retour

None

Remarques

NDIS appelle la fonction ProtocolCoOidRequestComplete pour terminer le traitement du client CoNDIS, du gestionnaire d’appels ou de la requête OID MCM pour laquelle la fonction NdisCoOidRequest ou la fonction NdisMCmOidRequest a retourné NDIS_STATUS_PENDING.

Pour inscrire ProtocolCoOidRequestComplete 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 ProtocolCoOidRequestComplete en tant que gestionnaire d’appels, un pilote initialise un NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS structure et la transmet au paramètre OptionalHandlers de NdisSetOptionalHandlers.

Le pilote cible est le pilote qui a servi la demande d’informations OID. Appel d’un pilote cible à NdisMCoOidRequestComplete, NdisCoOidRequestComplete ou La fonction NdisMCmOidRequestComplete a provoqué l’appel de la fonction ProtocolCoOidRequestComplete par NDIS. NDIS transfère la valeur du paramètre Status qui a été passé à ces fonctions en tant que paramètre d’état d’entrée à ProtocolCoOidRequestComplete.

ProtocolCoOidRequestComplete utilise la valeur d’entrée Status comme suit :

Si Status est NDIS_STATUS_SUCCESS, le membre BytesRead ou BytesWritten de la structure NDIS_OID_REQUEST vers laquelle pointe le paramètre OidRequest spécifie la quantité d’informations transférées de la mémoire tampon dans le membre InformationBuffer de NDIS_OID_REQUEST au pilote cible ou la quantité d’informations retournées dans InformationBuffer, respectivement.
Si le pilote a effectué une requête, ProtocolCoOidRequestComplete peut utiliser les données retournées dans InformationBuffer comme il convient pour la valeur spécifiée dans le membre Oid de NDIS_OID_REQUEST.
Si Status est NDIS_STATUS_INVALID_LENGTH ou NDIS_STATUS_BUFFER_TOO_SHORT, le membre BytesNeededed de la structure NDIS_OID_REQUEST vers laquelle pointe OidRequest spécifie la valeur spécifique à OID du membre InformationBufferLength de NDIS_OID_REQUEST nécessaire pour effectuer l’opération demandée.
Dans ces circonstances, ProtocolCoOidRequestComplete peut allouer suffisamment d’espace tampon pour la requête, configurer une autre structure NDIS_OID_REQUEST avec la valeur requise pour InformationBufferLength et réessayer la requête OID.
Si Status est une valeur xxx NDIS_STATUS_ qui est une erreur irrécupérable, ProtocolCoOidRequestComplete doit libérer la mémoire pour la structure NDIS_OID_REQUEST. ProtocolCoOidRequestComplete doit également déterminer si le pilote doit fermer la liaison ou ajuster ses informations d’état spécifiques à la liaison pour gérer les opérations d’E/S réseau continues sur la liaison.

Pour plus d’informations sur les OID définis par le système, consultez Les OID NDIS.

ProtocolCoOidRequestComplete peut être appelé avant que le pilote ait eu le temps d’inspecter le code status retourné par NdisCoOidRequest ou NdisMCmOidRequest.

NDIS appelle ProtocolCoOidRequestComplete à IRQL <= DISPATCH_LEVEL.

Exemples

Pour définir une fonction ProtocolCoOidRequestComplete , 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 ProtocolCoOidRequestComplete nommée « MyCoOidRequestComplete », utilisez le type PROTOCOL_CO_OID_REQUEST_COMPLETE comme indiqué dans cet exemple de code :

PROTOCOL_CO_OID_REQUEST_COMPLETE MyCoOidRequestComplete;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
VOID
 MyCoOidRequestComplete(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

Le type de fonction PROTOCOL_CO_OID_REQUEST_COMPLETE 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_COMPLETE 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 (voir la section Remarques)