PROTOCOL_OID_REQUEST_COMPLETE fonction de rappel (ndis.h)

Article
08/07/2023

La fonction ProtocolOidRequestComplete termine le traitement d’une requête OID initiée par le pilote de protocole pour laquelle la fonction NdisOidRequest a retourné NDIS_STATUS_PENDING.

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

Syntaxe

PROTOCOL_OID_REQUEST_COMPLETE ProtocolOidRequestComplete;

void ProtocolOidRequestComplete(
  [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 au pilote de protocole dans laquelle le pilote de protocole conserve l’état d’exécution par liaison. Le pilote a fourni ce handle lorsqu’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é passée à la fonction NdisOidRequest .

[in] Status

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

Valeur de retour

None

Remarques

ProtocolOidRequestComplete 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 a été défini par NDIS ou le pilote sous-jacent pour spécifier 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 d’une opération de jeu 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, ProtocolOidRequestComplete peut utiliser les données retournées dans InformationBuffer d’une manière déterminée par le pilote de protocole, 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, ProtocolOidRequestComplete 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 à la fonction NdisSendNetBufferLIsts .
Si Status est NDIS_STATUS_INVALID_LENGTH ou NDIS_STATUS_BUFFER_TOO_SHORT, le membre BytesNeededed spécifie la valeur spécifique à OID du membre InformationBufferLength requis pour effectuer l’opération demandée.
Dans ces circonstances, ProtocolOidRequestComplete peut allouer suffisamment d’espace tampon pour la requête, configurer une autre structure de NDIS_OID_REQUEST avec l’InformationBufferLength requis et le même Oid, puis réessayer l’appel à la fonction NdisOidRequest .

ProtocolOidRequestComplete peut également réessayer des demandes pour certains autres arguments NDIS_STATUS_ XXX , comme décrit dans la référence pour la fonction NdisOidRequest .
Si Status est une valeur xxx NDIS_STATUS_ qui est une erreur irrécupérable, ProtocolOidRequestComplete doit libérer la mémoire allouée pour 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.

Pour les requêtes et les ensembles globaux, l’appel du pilote miniport sans connexion sous-jacent à la fonction NdisMOidRequestComplete entraîne L’appel de la fonction ProtocolOidRequestComplete par NDIS. NDIS transfère l’état déterminé par le pilote miniport passé à NdisMOidRequestComplete en tant qu’état d’entrée à ProtocolOidRequestComplete.

Pour les requêtes spécifiques à une liaison, NDIS appelle la fonction ProtocolOidRequestComplete elle-même. Étant donné que la bibliothèque NDIS conserve les liaisons pour tous les pilotes miniports, NDIS peut retourner des informations spécifiques à la liaison uniquement sur les pilotes sous-jacents qui signalent leur type moyen comme un pour lequel le système fournit une bibliothèque de filtres. NDIS retourne NDIS_STATUS_NOT_SUPPORTED pour les requêtes spécifiques de liaison initiées par le pilote de protocole à d’autres pilotes miniports.

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

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

NDIS appelle ProtocolOidRequestComplete à IRQL <= DISPATCH_LEVEL.

Exemples

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

PROTOCOL_OID_REQUEST_COMPLETE MyOidRequestComplete;

Ensuite, implémentez votre fonction comme suit :

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

Le type de fonction PROTOCOL_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_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