PROTOCOL_BIND_ADAPTER_EX fonction de rappel (ndis.h)

NDIS appelle la fonction ProtocolBindAdapterEx d’un pilote de protocole pour demander au pilote de se 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 suivants.
 

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 au pilote dans laquelle le pilote gère les informations d’état et de configuration. Le pilote de protocole a passé cette zone de contexte au NdisRegisterProtocolDriver , fonction.

[in] BindContext

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

[in] BindParameters

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

Valeur de retour

ProtocolBindAdapterEx retourne l’une des valeurs d’état suivantes :

Code de retour Description
NDIS_STATUS_SUCCESS
ProtocolBindAdapterEx a correctement terminé la liaison à l’adaptateur miniport sous-jacent.
NDIS_STATUS_PENDING
ProtocolBindAdapterEx n’a pas terminé l’opération de liaison et l’opération est terminé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, un tel état d’erreur est propagé à partir d’une fonction NdisXxx ou d’une routine de prise en charge en mode noyau.

Remarques

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

ProtocolBindAdapterEx alloue suffisamment de mémoire pour maintenir les informations de contexte de liaison et appelle la fonction NdisOpenAdapterEx pour se lier à l’adaptateur miniport sous-jacent. ProtocolBindAdapterEx transmet un pointeur aux informations de contexte de liaison au paramètre ProtocolBindingContext de NdisOpenAdapterEx. ProtocolBindAdapterEx transmet la valeur au membre AdapterName à partir 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 transmettre le pointeur à BindParameters à la fonction NdisOpenConfigurationEx pour lire les paramètres de configuration associés à une carte miniport.

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

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 paramètre SelectedMediumIndex de la structure à OpenParameters.

Si NdisOpenAdapterEx retourne un état d’erreur, ProtocolBindAdapterEx retourne cet état d’erreur, 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 doit effectuer les E/S réseau sur la liaison. Le pilote peut également configurer toutes les informations de contexte spécifiques à la liaison que le pilote 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 ouverte 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 paramètre OpenParameters et la valeur du paramètre NdisBindingHandle après que NdisOpenAdapterEx retourne. 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 à 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 ouverte n’est pas terminée. Étant donné que la liaison est dans l’état suspendu une fois l’opération ouverte terminée, le pilote de protocole ne peut pas envoyer de requêtes tant qu’après le redémarrage de la liaison NDIS.

Une fois l’opération ouverte 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 vers une période 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 ouverte terminée, selon le média sous-jacent, le pilote de protocole peut appeler la fonction NdisOidRequest pour interroger le pilote miniport sous-jacent (ou NDIS) sur des fonctionnalités supplémentaires d’adaptateur miniport. Pour plus d’informations sur les requêtes OID, consultez Requêtes OID du pilote de protocole.

NDIS peut appeler les pilotes de protocole Fonction ProtocolReceiveNetBufferLists après la configuration d’un filtre de paquets pour la liaison avec 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 ouverte terminée. Les pilotes de protocole peuvent recevoir des indications d’état sur la fonction ProtocolStatusEx une fois l’opération ouverte terminée.

Chaque pilote de protocole doit allouer suffisamment 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 doit effectuer les opérations d’E/S réseau suivantes, elle doit libérer toutes les ressources qu’elle a déjà allouées et retourner une valeur d’erreur appropriée.

NDIS appelle les pilotes de protocole Fonction ProtocolUnbindAdapterEx pour demander au pilote de se déconnecter 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, en raison d’une requête OID ayant échoué), 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 la fin de l’opération de fermeture 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 à 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 fonctions aide l’analyse du code pour les pilotes, le vérificateur de pilotes statiques (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des 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 lorsque vous exécutez les outils d’analyse de 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 les exigences relatives aux 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 Annoter le comportement de la fonction.

Configuration requise

   
Client minimal pris en charge Pris en charge dans NDIS 6.0 et versions ultérieures.
Plateforme cible Windows
En-tête ndis.h (include Ndis.h)
IRQL PASSIVE_LEVEL

Voir aussi

NDIS_BIND_PARAMETERS

NDIS_MEDIUM

NET_BUFFER

NET_BUFFER_LIST

NdisCloseAdapterEx

NdisCompleteBindAdapterEx

NdisOidRequest

NdisOpenAdapterEx

NdisOpenConfigurationEx

NdisRegisterProtocolDriver

NdisUnbindAdapter

OID_GEN_CURRENT_PACKET_FILTER

ProtocolOpenAdapterCompleteEx ProtocolReceiveNetBufferLists

ProtocolStatusEx

ProtocolUnbindAdapterEx