Fonction IoReportTargetDeviceChange (wdm.h)

  • Article

La routine IoReportTargetDeviceChange avertit le gestionnaire PnP qu’un événement personnalisé s’est produit sur un appareil.

Syntaxe

NTSTATUS IoReportTargetDeviceChange(
  [in] PDEVICE_OBJECT PhysicalDeviceObject,
  [in] PVOID          NotificationStructure
);

Paramètres

[in] PhysicalDeviceObject

Pointeur vers l’AOP de l’appareil signalé.

[in] NotificationStructure

Pointeur vers une structure de TARGET_DEVICE_CUSTOM_NOTIFICATION fournie par l’appelant décrivant l’événement personnalisé. Le gestionnaire PnP envoie cette structure aux pilotes qui se sont inscrits pour la notification de l’événement.

NotificationStructure. FileObject doit avoir la valeur NULL. NotificationStructure. L’événement doit contenir le GUID personnalisé de l’événement. Les autres champs de l’objet NotificationStructure doivent être renseignés en fonction de l’événement personnalisé.

Le gestionnaire PnP remplit l’objet NotificationStructure. Champ FileObject lorsqu’il envoie des notifications aux inscrits.

Valeur retournée

IoReportTargetDeviceChange retourne STATUS_SUCCESS ou une erreur appropriée status. Les valeurs d’erreur status possibles sont les suivantes :

Code de retour Description
STATUS_INVALID_DEVICE_REQUEST
 L’appelant a spécifié un événement PnP système, tel que GUID_TARGET_DEVICE_QUERY_REMOVE. Cette routine s’adresse uniquement aux événements personnalisés.

Remarques

Une fois qu’IoReportTargetDeviceChange a averti le gestionnaire PnP qu’un événement personnalisé s’est produit sur un appareil, le gestionnaire PnP envoie une notification de l’événement aux pilotes inscrits pour la notification sur l’appareil. N’utilisez pas cette routine pour signaler des événements PnP système, tels que GUID_TARGET_DEVICE_REMOVE_COMPLETE.

Un pilote qui définit un événement d’appareil personnalisé appelle IoReportTargetDeviceChange pour informer le gestionnaire PnP que l’événement personnalisé s’est produit. Une notification personnalisée peut être utilisée pour des événements tels qu’une modification d’étiquette de volume.

Un pilote doit appeler la forme asynchrone de cette routine, IoReportTargetDeviceChangeAsynchronous, au lieu de cette routine, pour éviter les interblocages.

Certains composants en mode noyau peuvent appeler cette routine synchrone. Par exemple, un système de fichiers peut appeler IoReportTargetDeviceChange pour signaler un événement personnalisé « get off the volume » lorsqu’un composant tente d’ouvrir le volume pour un accès exclusif. Les clients qui s’inscrivent à la notification sur des volumes de système de fichiers veillent à ne pas demander une ouverture exclusive dans une routine de rappel de notification PnP.

La structure de notification personnalisée contient un événement défini par le pilote avec son propre GUID. Les enregistreurs de pilotes peuvent générer des GUID avec Uuidgen.exe ou Guidgen.exe (qui sont inclus dans le Microsoft Windows SDK).

Les appelants d’IoReportTargetDeviceChange doivent s’exécuter sur IRQL = PASSIVE_LEVEL dans le contexte d’un thread système. Pour signaler un changement d’appareil cible à partir de l’PASSIVE_LEVEL IRQL > , appelez IoReportTargetDeviceChangeAsynchronous.

IoReportTargetDeviceChange n’est pas pris en charge sur Windows 98/Me ; elle retourne STATUS_NOT_IMPLEMENTED.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Disponible à partir de Windows 2000.
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 (voir la section Remarques)
Règles de conformité DDI HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

Voir aussi

IoReportTargetDeviceChangeAsynchronous

TARGET_DEVICE_CUSTOM_NOTIFICATION