PROTOCOL_DIRECT_OID_REQUEST_COMPLETE fonction de rappel (ndis.h)

Article
08/07/2023

La fonction ProtocolDirectOidRequestComplete termine le traitement d’une requête OID directe initiée par le pilote de protocole pour laquelle la fonction NdisDirectOidRequest a renvoyé NDIS_STATUS_PENDING.

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

Syntaxe

PROTOCOL_DIRECT_OID_REQUEST_COMPLETE ProtocolDirectOidRequestComplete;

void ProtocolDirectOidRequestComplete(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNDIS_OID_REQUEST OidRequest,
  [in] NDIS_STATUS Status
)
{...}

Paramètres

[in] ProtocolBindingContext

Handle vers une zone de contexte allouée par le pilote de protocole dans laquelle le pilote de protocole maintient l’état d’exécution par liaison. Le pilote a fourni ce handle quand il a appelé la fonction NdisOpenAdapterEx .

[in] OidRequest

Pointeur vers la structure de NDIS_OID_REQUEST fournie par le pilote de protocole qui a été précédemment passée à la fonction NdisDirectOidRequest .

[in] Status

Dernier status de la demande. Le pilote sous-jacent ou NDIS détermine cette status finale. Ce paramètre détermine ce que ProtocolDirectOidRequestComplete fait avec les informations dans OidRequest.

Valeur de retour

None

Remarques

ProtocolDirectOidRequestComplete est une fonction facultative. Si un pilote de protocole n’utilise pas de requêtes OID directes, il peut définir le point d’entrée de cette fonction sur NULL lorsqu’il appelle le Fonction NdisRegisterProtocolDriver .

ProtocolDirectOidRequestComplete utilise la valeur d’entrée du paramètre Status comme suit :

Si Status est NDIS_STATUS_SUCCESS, le membre BytesRead ou BytesWritten de la structure NDIS_OID_REQUEST a été défini par NDIS ou le pilote sous-jacent. Ces valeurs spécifient la quantité d’informations fournies par le pilote de protocole qui ont été transférées de la mémoire tampon dans InformationBuffer vers la carte réseau dans une opération définie ou la quantité d’informations retournées dans InformationBuffer en réponse à une opération de requête.
Si le pilote de protocole a effectué une requête, ProtocolDirectOidRequestComplete peut utiliser les données retournées dans InformationBuffer d’une manière que le pilote de protocole détermine, en fonction de la valeur du membre Oid .

Par exemple, si le pilote de protocole a initialement lancé un OID_GEN_MAXIMUM_SEND_PACKETS requête, ProtocolDirectOidRequestComplete peut configurer des variables d’état dans la zone ProtocolBindingContext pour limiter le nombre d’envois en attente que le pilote configurera pour les appels suivants au Fonction NdisSendNetBufferLists .
Si Status est NDIS_STATUS_INVALID_LENGTH ou NDIS_STATUS_BUFFER_TOO_SHORT, le membre BytesNeeded spécifie la valeur spécifique à OID du membre InformationBufferLength requis pour effectuer l’opération demandée.
Dans ces circonstances, ProtocolDirectOidRequestComplete peut allouer suffisamment d’espace tampon pour la requête, configurer une autre structure de NDIS_OID_REQUEST avec la valeur InformationBufferLength requise et la même valeur Oid , puis réessayer l’appel à la fonction NdisDirectOidRequest .

ProtocolDirectOidRequestComplete peut également réessayer des demandes pour certains autres arguments xxx NDIS_STATUS_, comme décrit dans NdisDirectOidRequest.
Si Status est une valeur NDIS_STATUS_ Xxx qui est une erreur irrécupérable, ProtocolDirectOidRequestComplete doit libérer la mémoire allouée à la structure NDIS_OID_REQUEST et 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.

ProtocolDirectOidRequestComplete peut être appelé avant que le pilote de protocole ait eu le temps d’inspecter le code status que NdisDirectOidRequest retourne à Status.

NDIS appelle ProtocolDirectOidRequestComplete à l’adresse IRQL <= DISPATCH_LEVEL.

Exemples

Pour définir une fonction ProtocolDirectOidRequestComplete , 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, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. 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 ProtocolDirectOidRequestComplete nommée « MyDirectOidRequestComplete », utilisez le type PROTOCOL_DIRECT_OID_REQUEST_COMPLETE comme indiqué dans cet exemple de code :

PROTOCOL_DIRECT_OID_REQUEST_COMPLETE MyDirectOidRequestComplete;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
VOID
 MyDirectOidRequestComplete(
    NDIS_HANDLE  ProtocolBindingContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

Le type de fonction PROTOCOL_DIRECT_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_DIRECT_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.1 et versions ultérieures.
Plateforme cible	Windows
En-tête	ndis.h (inclure Ndis.h)
IRQL	<= DISPATCH_LEVEL