PROTOCOL_UNBIND_ADAPTER_EX fonction de rappel (ndis.h)

Article
02/29/2024

NDIS appelle la fonction ProtocolUnbindAdapterEx d’un pilote de protocole pour demander au pilote de se détacher d’une carte miniport sous-jacente.

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

Syntaxe

PROTOCOL_UNBIND_ADAPTER_EX ProtocolUnbindAdapterEx;

NDIS_STATUS ProtocolUnbindAdapterEx(
  [in] NDIS_HANDLE UnbindContext,
  [in] NDIS_HANDLE ProtocolBindingContext
)
{...}

Paramètres

[in] UnbindContext

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

[in] ProtocolBindingContext

Handle à une zone de contexte allouée par le pilote de protocole. Le pilote de protocole conserve les informations de contexte par liaison dans cette zone de contexte. Le pilote a fourni ce handle à NDIS lorsque le pilote a appelé la fonction NdisOpenAdapterEx .

Valeur retournée

ProtocolUnbindAdapterEx retourne l’une des valeurs status suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	ProtocolUnbindAdapterEx a réussi à se détacher d’un adaptateur miniport sous-jacent.
NDIS_STATUS_PENDING	ProtocolUnbindAdapterEx n’a pas terminé l’opération unbind et l’opération sera effectuée de manière asynchrone. Le pilote de protocole doit appeler le Fonction NdisCompleteUnbindAdapterEx une fois l’opération unbind terminée.

Remarques

ProtocolUnbindAdapterEx est une fonction obligatoire. En tant que réciproque de la fonction ProtocolBindAdapterEx , NDIS appelle ProtocolUnbindAdapterEx pour libérer les ressources allouées par le pilote pour les opérations d’E/S réseau spécifiques à une liaison. Un pilote de protocole ne peut pas échouer une opération sans liaison.

Avant d’appeler ProtocolUnbindAdapterEx, NDIS suspend la liaison de protocole. Pour suspendre la liaison, NDIS appelle la fonction ProtocolNetPnPEvent et spécifie un événement NetEventPause .

ProtocolUnbindAdapterEx doit appeler la fonction NdisCloseAdapterEx pour fermer la liaison à l’adaptateur miniport sous-jacent. Si NdisCloseAdapterEx retourne NDIS_STATUS_SUCCESS, l’opération de fermeture est terminée. Si NdisCloseAdapterEx retourne NDIS_STATUS_PENDING, NDIS appelle le pilote de protocole Fonction ProtocolCloseAdapterCompleteEx une fois l’opération de fermeture terminée.

Avant d’appeler NdisCloseAdapterEx, le pilote de protocole doit effacer la liste d’adresses de multidiffusion et les filtres de paquets pour la liaison. Le pilote de protocole définit la liste d’adresses de multidiffusion de liaison sur NULL et le filtre de paquets sur zéro. Pour plus d’informations, consultez OID_802_3_MULTICAST_LIST et OID_GEN_CURRENT_PACKET_FILTER.

Si un modèle de mise en éveil a été spécifié, le pilote de protocole doit le supprimer avec le OID_PNP_REMOVE_WAKE_UP_PATTERN OID et effacer les paramètres de mise à l’échelle côté réception avec le OID_GEN_RECEIVE_SCALE_PARAMETERS OID. Un pilote de protocole NDIS 6.20 et versions ultérieures doit supprimer un modèle wake-on-LAN avec l’OID OID_PM_REMOVE_WOL_PATTERN et supprimer un déchargement de protocole à faible consommation d’énergie avec l’OID OID_PM_REMOVE_PROTOCOL_OFFLOAD .

ProtocolUnbindAdapterEx ne doit pas libérer la mémoire sur ProtocolBindingContext tant que l’opération de fermeture n’est pas terminée. NDIS transmet le handle à ProtocolBindingContext à ProtocolCloseAdapterCompleteEx.

Si le pilote de protocole a terminé l’opération unbind, ProtocolUnbindAdapterEx peut retourner NDIS_STATUS_SUCCESS. Si NdisCloseAdapterEx retourne NDIS_STATUS_PENDING, ProtocolUnbindAdapterEx doit attendre que NDIS appelle ProtocolCloseAdapterCompleteEx avant de pouvoir retourner NDIS_STATUS_SUCCESS.

ProtocolUnbindAdapterEx peut renvoyer NDIS_STATUS_PENDING pour reporter l’achèvement de l’opération unbind à une date ultérieure. Si ProtocolUnbindAdapterEx retourne NDIS_STATUS_PENDING, le pilote doit finalement appeler le Fonction NdisCompleteUnbindAdapterEx pour terminer l’opération unbind. Si la fonction NdisCloseAdapterEx a retourné NDIS_STATUS_PENDING, le pilote peut effectuer l’opération sans liaison dans ProtocolCloseAdapterCompleteEx. ProtocolUnbindAdapterEx peut stocker le handle dans UnbindContext dans la zone de contexte de ProtocolBindingContext avant d’appeler NdisCloseAdapterEx. Si ProtocolUnbindAdapterEx a stocké le handle, ProtocolCloseAdapterCompleteEx peut passer le handle à NdisCompleteUnbindAdapterEx pour terminer l’opération unbind.

Dès que ProtocolUnbindAdapterEx appelle NdisCloseAdapterEx, le handle obtenu à partir de la fonction NdisOpenAdapterEx au niveau du paramètre NdisBindingHandle devient non valide. ProtocolUnbindAdapterEx ne peut pas effectuer d’appels ultérieurs aux fonctions NdisXxx avec ce handle. Le pilote peut obtenir des indications de réception et de status à partir de l’adaptateur miniport sous-jacent jusqu’à ce que l’opération de fermeture soit terminée.

NDIS appelle ProtocolUnbindAdapterEx à IRQL = PASSIVE_LEVEL.

Mise à jour de la gestion de l’alimentation et des paramètres RSS

Les pilotes de protocole NDIS 6.0 et 6.1 doivent effectuer les opérations suivantes le cas échéant :

Supprimer les modèles de veille de gestion de l’alimentation sur le réseau local (WOL) de l’adaptateur miniport avec le OID_PNP_REMOVE_WAKE_UP_PATTERN OID.
Effacez les paramètres de mise à l’échelle côté réception avec le OID_GEN_RECEIVE_SCALE_PARAMETERS OID.

Les pilotes de protocole NDIS 6.20 et versions ultérieures doivent effectuer les opérations suivantes :

Supprimez les modèles WOL de gestion de l’alimentation de l’adaptateur miniport avec le OID_PM_REMOVE_WOL_PATTERN OID.
Supprimer les déchargements du protocole de gestion de l’alimentation de l’adaptateur miniport avec le OID_PM_REMOVE_PROTOCOL_OFFLOAD OID.

Exemples

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

PROTOCOL_UNBIND_ADAPTER_EX MyUnbindAdapterEx;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
NDIS_STATUS
 MyUnbindAdapterEx(
    NDIS_HANDLE  UnbindContext,
    NDIS_HANDLE  ProtocolBindingContext
    )
  {...}

Le type de fonction PROTOCOL_UNBIND_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_UNBIND_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 pour NDIS 6.0 et versions ultérieures.
Plateforme cible	Windows
En-tête	ndis.h (inclure Ndis.h)
IRQL	PASSIVE_LEVEL