Fonction IoRegisterPlugPlayNotification (wdm.h)

Article
10/20/2023

La routine IoRegisterPlugPlayNotification enregistre une routine de rappel de notification Plug-and-Play (PnP) à appeler lorsqu’un événement PnP de la catégorie spécifiée se produit.

Syntaxe

NTSTATUS IoRegisterPlugPlayNotification(
  [in]           IO_NOTIFICATION_EVENT_CATEGORY        EventCategory,
  [in]           ULONG                                 EventCategoryFlags,
  [in, optional] PVOID                                 EventCategoryData,
  [in]           PDRIVER_OBJECT                        DriverObject,
  [in]           PDRIVER_NOTIFICATION_CALLBACK_ROUTINE CallbackRoutine,
  [in, optional] __drv_aliasesMem PVOID                Context,
  [out]          PVOID                                 *NotificationEntry
);

Paramètres

[in] EventCategory

Spécifie une valeur d’énumération de IO_NOTIFICATION_EVENT_CATEGORY qui indique la catégorie d’événement PnP pour laquelle la routine de rappel est inscrite.

[in] EventCategoryFlags

Indicateurs de bits qui modifient l’opération d’inscription. Les valeurs possibles incluent :

PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES

Valide uniquement avec un EventCategory de EventCategoryDeviceInterfaceChange. S’il est défini, le gestionnaire PnP appelle la routine de rappel de pilote pour chaque interface d’appareil instance actuellement inscrite et active et inscrit la routine de rappel pour les arrivées ou suppressions futures d’instances d’interface d’appareil.

[in, optional] EventCategoryData

Pointeur vers des informations supplémentaires sur les événements pour lesquels CallbackRoutine est inscrit. Les informations varient pour différentes valeurs EventCategory :

Lorsque EventCategory est EventCategoryDeviceInterfaceChange, EventCategoryData doit pointer vers un GUID spécifiant une classe d’interface d’appareil. CallbackRoutine est appelé lorsqu’une interface de cette classe est activée ou supprimée.
Lorsque EventCategory a la valeur EventCategoryHardwareProfileChange, EventCategoryData doit avoir la valeur NULL.
Lorsque EventCategory est EventCategoryTargetDeviceChange, EventCategoryData doit pointer vers l’objet fichier pour lequel la notification PnP est demandée.

[in] DriverObject

Pointeur vers l’objet pilote de l’appelant.

Pour garantir que le pilote reste chargé pendant qu’il est inscrit pour la notification PnP, cet appel incrémente le nombre de références sur DriverObject. Le gestionnaire PnP décrémente le nombre de références lorsque cette inscription est supprimée.

Pour EventCategoryTargetDeviceChange, DriverObject ne doit pas être l’objet pilote de l’appareil cible ; il doit plutôt s’agir de l’objet pilote du pilote qui implémente CallbackRoutine.

[in] CallbackRoutine

Pointeur vers la routine de rappel de notification PnP à appeler lorsque l’événement PnP spécifié se produit.

Le prototype de fonction pour cette routine de rappel est défini comme suit :

typedef NTSTATUS
  DRIVER_NOTIFICATION_CALLBACK_ROUTINE(
    _In_ PVOID NotificationStructure,
    _Inout_opt_ PVOID Context
    );

NotificationStructure de la routine de rappel est spécifique à la valeur EventCategory, comme indiqué dans le tableau suivant.

Catégorie d'événements	Structure de notification
EventCategoryDeviceInterfaceChange	DEVICE_INTERFACE_CHANGE_NOTIFICATION
EventCategoryHardwareProfileChange	HWPROFILE_CHANGE_NOTIFICATION
EventCategoryTargetDeviceChange	TARGET_DEVICE_REMOVAL_NOTIFICATION Pour plus d’informations, consultez Utilisation de la notification PnP et TARGET_DEVICE_CUSTOM_NOTIFICATION.

Le paramètre Context de la routine de rappel contient les données de contexte fournies par le pilote lors de l’inscription.

Pour plus d’informations sur l’inclusion d’une déclaration de fonction pour la routine de rappel qui répond aux exigences de Static Driver Verifier (SDV), consultez Exemples.

Le gestionnaire PnP appelle des routines de rappel de pilote à IRQL = PASSIVE_LEVEL.

[in, optional] Context

Pointeur vers une mémoire tampon allouée à l’appelant contenant le contexte que le gestionnaire PnP transmet à la routine de rappel.

[out] NotificationEntry

Pointeur vers une valeur opaque retournée par cet appel qui identifie l’inscription. Transmettez cette valeur à la routine IoUnregisterPlugPlayNotificationEx pour supprimer l’inscription.

Valeur retournée

IoRegisterPlugPlayNotification retourne STATUS_SUCCESS ou une status d’erreur appropriée.

Remarques

Un pilote s’inscrit pour une catégorie d’événement. Chaque catégorie inclut un ou plusieurs types d’événements PnP.

Un pilote peut inscrire différentes routines de rappel pour différentes catégories d’événements ou peut inscrire une seule routine de rappel. Une routine de rappel unique peut convertir notificationStructure en PLUGPLAY_NOTIFICATION_HEADER et utiliser le champ Event pour déterminer le type exact de la structure de notification.

Si l’appelant spécifie PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES, le système d’exploitation peut appeler la routine de rappel de notification PnP deux fois pour un événement EventCategoryDeviceInterfaceChange unique pour une interface existante. Vous pouvez ignorer en toute sécurité le deuxième appel au rappel. Le système d’exploitation n’appelle pas le rappel plus de deux fois pour un seul événement.

Les routines de rappel de notification PnP doivent effectuer leurs tâches aussi rapidement que possible et retourner le contrôle au gestionnaire PnP, afin d’éviter les retards dans la notification des autres pilotes et applications qui se sont inscrits pour l’événement.

Le gestionnaire PnP ne prend pas de référence sur l’objet file lorsqu’un pilote s’inscrit pour la notification d’un événement EventCategoryTargetDeviceChange . Si la routine de rappel de notification PnP du pilote nécessite un accès à l’objet fichier, le pilote doit prendre une référence supplémentaire sur l’objet fichier avant d’appeler IoRegisterPlugPlayNotification.

En règle générale, les pilotes Kernel-Mode Driver Framework (KMDF) doivent appeler IoRegisterPlugPlayNotification à partir de leur fonction de rappel EvtDeviceSelfManagedIoInit et doivent appeler IoUnregisterPlugPlayNotification à partir de leur fonction de rappel EvtDeviceSelfManagedIoCleanup . Ces pilotes ne doivent pas appeler IoRegisterPlugPlayNotification à partir de leur fonction de rappel EvtDriverDeviceAdd ; Sinon, la routine de rappel de notification PnP peut être appelée avant le démarrage de la pile de pilotes par PnP, auquel cas le pilote ne sera pas prêt à gérer la notification.

Pour plus d’informations, consultez Utilisation de la notification PnP.

Exemples

Pour définir une routine de rappel de notification PnP, vous devez d’abord fournir une déclaration de fonction qui identifie le type de routine de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction de rappel 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 routine de rappel de notification PnP nommée MyCallbackRoutine, utilisez le type DRIVER_NOTIFICATION_CALLBACK_ROUTINE comme indiqué dans cet exemple de code :

DRIVER_NOTIFICATION_CALLBACK_ROUTINE MyCallbackRoutine;

Ensuite, implémentez votre routine de rappel comme suit :

_Use_decl_annotations_
NTSTATUS
  MyCallbackRoutine(
    PVOID NotificationStructure,
    PVOID Context
    )
  {
      // Function body
  }

Le type de fonction DRIVER_NOTIFICATION_CALLBACK_ROUTINE est défini dans le fichier d’en-tête Wdm.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 DRIVER_NOTIFICATION_CALLBACK_ROUTINE 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 WDM. Pour plus d’informations sur _Use_decl_annotations_, consultez Annotating Function Behavior.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)