PROTOCOL_BIND_ADAPTER_EX fonction de rappel (ndis.h)

Article
08/07/2023

NDIS appelle la fonction ProtocolBindAdapterEx d’un pilote de protocole pour demander au pilote de lier à un adaptateur miniport.

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

Syntaxe

PROTOCOL_BIND_ADAPTER_EX ProtocolBindAdapterEx;

NDIS_STATUS ProtocolBindAdapterEx(
  [in] NDIS_HANDLE ProtocolDriverContext,
  [in] NDIS_HANDLE BindContext,
  [in] PNDIS_BIND_PARAMETERS BindParameters
)
{...}

Paramètres

[in] ProtocolDriverContext

Handle vers une zone de contexte allouée par le pilote où le pilote conserve les informations d’état et de configuration. Le pilote de protocole a passé cette zone de contexte au Fonction NdisRegisterProtocolDriver .

[in] BindContext

Handle qui identifie la zone de contexte NDIS pour cette opération de liaison.

[in] BindParameters

Pointeur vers une structure de NDIS_BIND_PARAMETERS créée par NDIS.

Valeur retournée

ProtocolBindAdapterEx retourne l’une des valeurs de status suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	ProtocolBindAdapterEx a correctement effectué la liaison à l’adaptateur miniport sous-jacent.
NDIS_STATUS_PENDING	ProtocolBindAdapterEx n’a pas terminé l’opération de liaison et l’opération sera effectuée de manière asynchrone. Le pilote de protocole doit appeler le Fonction NdisCompleteBindAdapterEx lorsque l’opération est terminée.
NDIS_STATUS_RESOURCES	ProtocolBindAdapterEx n’a pas pu allouer les ressources dont le pilote a besoin pour effectuer des opérations d’E/S réseau.
NDIS_STATUS_XXX ou NTSTATUS_XXX	La tentative de configuration d’une liaison par le pilote de protocole a échoué. En règle générale, une telle erreur status est propagée à partir d’une fonction NdisXxx ou d’une routine de prise en charge en mode noyau.

Remarques

ProtocolBindAdapterEx est une fonction obligatoire. NDIS appelle ProtocolBindAdapterEx pour effectuer des opérations de liaison chaque fois qu’un adaptateur miniport sous-jacent, auquel le pilote de protocole peut se lier, est disponible.

ProtocolBindAdapterEx alloue suffisamment de mémoire pour conserver les informations de contexte de liaison et appelle la fonction NdisOpenAdapterEx pour se lier à l’adaptateur miniport sous-jacent. ProtocolBindAdapterEx passe un pointeur vers les informations de contexte de liaison au niveau du paramètre ProtocolBindingContext de NdisOpenAdapterEx. ProtocolBindAdapterEx transmet la valeur au membre AdapterName de son paramètre BindParameters en tant que membre AdapterName du paramètre OpenParameters de NdisOpenAdapterEx.

Avant que le pilote appelle NdisOpenAdapterEx, le pilote peut passer le pointeur sur BindParameters à la fonction NdisOpenConfigurationEx pour lire les paramètres de configuration associés à un adaptateur miniport.

Après avoir ouvert correctement l’adaptateur miniport, le pilote peut passer le handle du paramètre NdisHandle de NdisOpenAdapterEx à NdisOpenConfigurationEx pour obtenir un handle à l’emplacement du Registre où sont stockés les paramètres de configuration d’une liaison de protocole.

ProtocolBindAdapterEx transmet À NdisOpenAdapterEx un pointeur vers un tableau de valeurs de type moyen qui répertorie les types de média que le pilote de protocole peut prendre en charge. Cette liste est un sous-ensemble des types NDIS_MEDIUM . NDIS indique le type moyen sélectionné au niveau du paramètre SelectedMediumIndex de la structure dans OpenParameters.

Si NdisOpenAdapterEx renvoie une erreur status, ProtocolBindAdapterEx retourne cette erreur status, libère toutes les ressources par liaison allouées par le pilote de protocole et retourne immédiatement le contrôle.

Si NdisOpenAdapterEx retourne NDIS_STATUS_SUCCESS, ProtocolBindAdapterEx peut allouer les ressources restantes dont le pilote de protocole a besoin pour effectuer des E/S réseau sur la liaison. Le pilote peut également configurer toutes les informations de contexte spécifiques à la liaison qu’il utilise pour suivre les opérations d’E/S réseau.

Si NdisOpenAdapterEx retourne NDIS_STATUS_PENDING, NDIS appelle le pilote de protocole Fonction ProtocolOpenAdapterCompleteEx une fois l’opération d’ouverture terminée. ProtocolOpenAdapterCompleteEx peut effectuer les opérations de liaison. ProtocolBindAdapterEx peut stocker le handle BindContext dans la zone de contexte de liaison. NDIS transmet ProtocolBindingContext comme paramètre d’entrée à la fonction ProtocolOpenAdapterCompleteEx du pilote.

Si NdisOpenAdapterEx retourne NDIS_STATUS_PENDING, NDIS définit le membre SelectedMediumIndex de la structure au niveau du paramètre OpenParameters et la valeur du paramètre NdisBindingHandle après le retour de NdisOpenAdapterEx . NDIS définit ces valeurs avant d’appeler ProtocolOpenAdapterCompleteEx. Par conséquent, le pilote de protocole doit stocker la structure des paramètres ouverts et le handle de liaison de protocole dans la zone de contexte dans ProtocolBindingContext(ou tout emplacement valide jusqu’à ce que NDIS appelle ProtocolOpenAdapterCompleteEx).

Un pilote de protocole ne peut pas effectuer de requêtes OID sur une liaison tant que l’opération d’ouverture n’est pas terminée. Étant donné que la liaison est dans l’état suspendu une fois l’opération d’ouverture terminée, le pilote de protocole ne peut pas effectuer d’envoi de demandes tant que NDIS n’a pas redémarré la liaison.

Une fois l’opération d’ouverture terminée, ProtocolBindAdapterEx peut retourner NDIS_STATUS_SUCCESS pour terminer l’opération de liaison. ProtocolBindAdapterEx peut retourner NDIS_STATUS_PENDING pour différer l’achèvement des opérations de liaison à une date ultérieure. Si ProtocolBindAdapterEx retourne NDIS_STATUS_PENDING, le pilote doit appeler le Fonction NdisCompleteBindAdapterEx une fois l’opération de liaison terminée.

Les pilotes de protocole doivent utiliser la structure NDIS_BIND_PARAMETERS pour déterminer les fonctionnalités de l’adaptateur miniport sous-jacent. Une fois l’opération d’ouverture terminée, en fonction du support sous-jacent, le pilote de protocole peut appeler la fonction NdisOidRequest pour interroger le pilote miniport sous-jacent (ou NDIS) sur les fonctionnalités supplémentaires de l’adaptateur miniport. Pour plus d’informations sur les requêtes OID, consultez Requêtes OID du pilote de protocole.

NDIS peut appeler un pilote de protocole Fonction ProtocolReceiveNetBufferLists après que le pilote a configuré un filtre de paquets pour la liaison avec le OID_GEN_CURRENT_PACKET_FILTER OID. Si l’adaptateur miniport sous-jacent n’utilise pas de filtre de paquets pour les paquets entrants, les indications de réception sont activées une fois l’opération d’ouverture terminée. Les pilotes de protocole peuvent recevoir status indications au niveau de la fonction ProtocolStatusEx une fois l’opération d’ouverture terminée.

Chaque pilote de protocole doit allouer suffisamment de NET_BUFFER et NET_BUFFER_LIST pools de structures. Le pilote alloue des descripteurs de données réseau à partir de ces pools pour les opérations d’envoi suivantes.

Si ProtocolBindAdapterEx ne peut pas allouer les ressources dont il a besoin pour effectuer les opérations d’E/S réseau suivantes, il doit libérer toutes les ressources qu’il a déjà allouées et retourner une valeur d’erreur appropriée.

NDIS appelle un pilote de protocole Fonction ProtocolUnbindAdapterEx pour demander au pilote de se dissocier d’un adaptateur miniport sous-jacent.

Si le pilote de protocole ouvre correctement l’adaptateur miniport mais que l’opération de liaison échoue (par exemple, suite à un échec d’une demande OID), le pilote doit fermer l’adaptateur miniport à partir du contexte de ProtocolBindAdapterEx ou ProtocolUnbindAdapterEx. Par exemple, le pilote appelle NdisCloseAdapterEx à partir de ProtocolBindAdapterEx et attend que l’opération de fermeture se termine avant que le pilote ne retourne à partir de ProtocolBindAdapterEx. En guise d’alternative, si le pilote a retourné NDIS_STATUS_PENDING à partir de ProtocolBindAdapterEx, le pilote peut appeler la fonction NdisUnbindAdapter Et appeler NdisCloseAdapterEx dans la fonction ProtocolUnbindAdapterEx .

NDIS appelle ProtocolBindAdapterEx à l’adresse IRQL = PASSIVE_LEVEL.

Exemples

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

PROTOCOL_BIND_ADAPTER_EX MyBindAdapterEx;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
NDIS_STATUS
 MyBindAdapterEx(
    NDIS_HANDLE  ProtocolDriverContext,
    NDIS_HANDLE  BindContext,
    PNDIS_BIND_PARAMETERS  BindParameters
    )
  {...}

Le type de fonction PROTOCOL_BIND_ADAPTER_EX 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_BIND_ADAPTER_EX 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	PASSIVE_LEVEL