PROTOCOL_NET_PNP_EVENT fonction de rappel (ndis.h)

Article
08/07/2023

NDIS appelle la fonction ProtocolNetPnPEvent pour indiquer un événement de Plug-and-Play réseau, un événement PnP NDIS ou un événement de gestion de l’alimentation à un pilote de protocole.

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

Syntaxe

PROTOCOL_NET_PNP_EVENT ProtocolNetPnpEvent;

NDIS_STATUS ProtocolNetPnpEvent(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNET_PNP_EVENT_NOTIFICATION NetPnPEventNotification
)
{...}

Paramètres

[in] ProtocolBindingContext

Handle d’une zone de contexte allouée par le pilote de protocole dans laquelle ce pilote conserve les informations d’état d’exécution par liaison. Le pilote de protocole a fourni ce handle lorsqu’il a appelé la fonction NdisOpenAdapterEx . Un événement NetEventXxx indiqué avec un protocole NULLBindingContext s’applique à toutes les liaisons. NetEventBindList et NetEventBindsComplete sont toujours indiqués avec un protocole NULLBindingContext. NetEventReconfigure peut être indiqué avec un ProtocoleBindingContext spécifié ou avec un Protocole NULLBindingContext.

[in] NetPnPEventNotification

Pointeur vers un NET_PNP_EVENT_NOTIFICATION structure qui décrit l’événement Plug-and-Play ou l’événement de gestion de l’alimentation que NDIS indique au pilote de protocole.

Valeur retournée

ProtocolNetPnPEvent peut retourner l’un des éléments suivants :

Code de retour	Description
NDIS_STATUS_SUCCESS	Le pilote de protocole a correctement géré l’événement de Plug-and-Play réseau indiqué, l’événement PnP NDIS ou l’événement de gestion de l’alimentation. La signification de ce code status dépend du code NetEvent dans la mise en mémoire tampon NET_PNP_EVENT_NOTIFICATION structure sur NetPnPEvent : NetEventSetPower Le pilote de protocole a effectué toutes les actions spécifiques au pilote qui sont nécessaires pour préparer la transition de l’appareil vers l’état d’alimentation de l’appareil demandé. NetEventQueryPower L’adaptateur sous-jacent peut passer à l’état d’alimentation de l’appareil demandé. NetEventQueryRemoveDevice L’adaptateur sous-jacent peut être supprimé. NetEventCancelRemoveDevice Le pilote de protocole a effectué toutes les actions spécifiques au pilote qui sont nécessaires pour préparer la suppression annulée de l’adaptateur sous-jacent. NetEventReconfigure Le pilote de protocole a accepté la configuration modifiée. NetEventBindList Le pilote de protocole a la nouvelle liste de liaisons et a effectué le traitement associé. NetEventBindsComplete Le pilote de protocole a reconnu l’indication de NDIS que le pilote de protocole est lié à toutes les cartes sous-jacentes disponibles. NetEventPnPCapabilities Le pilote de protocole a reconnu qu’il a reçu les fonctionnalités de mise en éveil actuelles de l’adaptateur sous-jacent associé à la liaison spécifiée. NetEventPause La liaison de protocole spécifiée est entrée à l’état Suspension . La liaison entre dans l’état Suspendu une fois que NDIS a terminé toutes les demandes d’envoi en suspens pour la liaison. Pour plus d’informations sur les opérations de pause, consultez Suspension d’une liaison. NetEventRestart La liaison de protocole spécifiée est entrée à l’état redémarrage . Une fois que le pilote de protocole est prêt à reprendre les opérations d’envoi et de réception pour la liaison, la liaison passe à l’état En cours d’exécution . NetEventPortActivation Le pilote de protocole a reconnu l’activation d’un port associé à la liaison spécifiée. Pour plus d’informations sur l’activation de port, consultez Activation d’un port NDIS. NetEventPortDeactivation Le pilote de protocole a reconnu l’activation d’un port associé à la liaison spécifiée.
NDIS_STATUS_PENDING	Le pilote de protocole retourne sa réponse à l’événement indiqué de manière asynchrone avec un appel à Fonction NdisCompleteNetPnPEvent .
NDIS_STATUS_RESOURCES	Le pilote de protocole n’a pas pu obtenir les ressources système nécessaires pour répondre à l’événement Plug-and-Play ou gestion de l’alimentation indiqué.
NDIS_STATUS_NOT_SUPPORTED	Les pilotes de protocole NDIS 6.0 et versions ultérieures ne doivent pas retourner cette status. NDIS 5. X pilote de protocole qui ne prend pas en charge Plug-and-Play peut retourner cette status en réponse à un NetEventSetPower pour indiquer que NDIS doit le dissocier de l’adaptateur sous-jacent.
NDIS_STATUS_FAILURE	Le pilote de protocole a échoué à l’événement indiqué pour des raisons autres que celles indiquées dans la liste précédente.

Un pilote de protocole peut faire échouer les événements NetEventQueryRemoveDevice et NetEventPortActivation .

Si un pilote de protocole échoue à l’événement NetEventPortActivation , il ne doit pas utiliser de ports associés dans les opérations suivantes.

Un pilote de protocole doit toujours réussir les événements NetEventRestart, NetEventIMReEnableDevice, NetEventCancelRemoveDevice, NetEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPause, NetEventPortDeactivation et NetEventPnPCapabilities en retournant NDIS_STATUS_SUCCESS.

Remarques

La fonction ProtocolNetPnPEvent est requise dans les pilotes de protocole pour prendre en charge Plug-and-Play et la gestion de l’alimentation. NDIS appelle ProtocolNetPnPEvent pour notifier un pilote de protocole qu’un événement de Plug-and-Play réseau, un événement PnP NDIS ou un événement De gestion de l’alimentation s’est produit.

The NET_PNP_EVENT_NOTIFICATION structure passée à ProtocolNetPnPEvent décrit l’événement. ProtocolNetPnPEvent interprète deux informations de base dans la structure NET_PNP_EVENT_NOTIFICATION :

Code dans le membre NetEvent qui identifie le type d’événement Plug-and-Play ou power Management.
Informations spécifiques à l’événement. Par exemple, avec un événement NetEventSetPower , le membre Buffer contient l’état d’alimentation de l’appareil vers lequel l’appareil effectue la transition.

Le pilote de protocole doit enregistrer le pointeur NetPnPEvent . Ce pointeur est un paramètre d’entrée obligatoire pour la fonction NdisCompleteNetPnPEvent , que le pilote de protocole doit appeler par la suite si ProtocolNetPnPEvent retourne NDIS_STATUS_PENDING.

Un pilote de protocole doit toujours réussir un événement NetEventQueryPower . Après avoir établi une connexion active, un pilote de protocole peut appeler la fonction PoRegisterSystemState pour inscrire un état occupé en permanence. Tant que l’inscription d’état est en vigueur, le gestionnaire d’alimentation ne tente pas de mettre le système en veille. Une fois la connexion inactive, le pilote de protocole annule l’inscription d’état en appelant la fonction PoUnregisterSystemState . Un pilote de protocole ne doit jamais essayer d’empêcher le système de passer à l’état de veille en échouant un événement NetEventQueryPower . Notez qu’un événement NetEventQueryPower est toujours suivi d’un événement NetEventSetPower . Un événement NetEventSetPower qui spécifie l’état d’alimentation actuel de l’appareil sous-jacent en vigueur annule l’événement NetEventQueryPower .

Si un pilote de protocole ne peut pas libérer un appareil (par exemple, parce que l’appareil est en cours d’utilisation), il doit échouer un événement NetEventQueryRemoveDevice en retournant NDIS_STATUS_FAILURE.

Un pilote de protocole doit toujours réussir un NetEventCancelRemoveDevice, un NetEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPnPCapabilities, NetEventPause ou NetEventPortDeactivation en retournant NDIS_STATUS_SUCCESS.

Lors de la gestion d’un NetEventReconfigure ou d’un NetEventBindList, un pilote de protocole doit valider les données associées à l’événement. Pour plus d’informations sur ces données, consultez NET_PNP_EVENT_NOTIFICATION.

NDIS appelle ProtocolNetPnPEvent à IRQL = PASSIVE_LEVEL.

Exemples

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

PROTOCOL_NET_PNP_EVENT MyNetPnPEvent;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
NDIS_STATUS
 MyNetPnPEvent(
    NDIS_HANDLE  ProtocolBindingContext,
    PNET_PNP_EVENT_NOTIFICATION  NetPnPEvent
    )
  {...}

Le type de fonction PROTOCOL_NET_PNP_EVENT 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_NET_PNP_EVENT 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