Fonction IoReportTargetDeviceChangeAsynchronous (wdm.h)

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

Syntaxe

NTSTATUS IoReportTargetDeviceChangeAsynchronous(
  [in]           PDEVICE_OBJECT                   PhysicalDeviceObject,
  [in]           PVOID                            NotificationStructure,
  [in, optional] PDEVICE_CHANGE_COMPLETE_CALLBACK Callback,
  [in, out]      PVOID                            Context
);

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 inscrits pour la notification de l’événement.

Cette structure fournie par l’appelant peut être libérée une fois la routine retournée, car le gestionnaire PnP effectue une copie superficielle et utilise la copie pour notifier les pilotes. La copie est automatiquement libérée par le gestionnaire PnP une fois qu’elle n’est plus nécessaire. Consultez la section Remarques sur les exigences du pool d’allocation.

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

Le gestionnaire PnP remplit notificationStructure. Champ FileObject lorsqu’il envoie des notifications aux inscrits.

[in, optional] Callback

Pointe éventuellement vers une routine fournie par l’appelant que le gestionnaire PnP appelle une fois qu’il a terminé de notifier les pilotes qui se sont inscrits pour cet événement personnalisé.

La routine de rappel a le type suivant :

typedef
VOID
(*PDEVICE_CHANGE_COMPLETE_CALLBACK)(
    IN PVOID Context
    );

Une routine de rappel de modification d’appareil ne doit pas bloquer et ne doit pas appeler des routines synchrones qui génèrent des événements PnP.

Le gestionnaire PnP appelle les routines de rappel de changement d’appareil à IRQL = PASSIVE_LEVEL.

[in, out] Context

Pointe éventuellement vers une structure de contexte fournie par l’appelant que le gestionnaire PnP transmet à la routine de rappel . L’appelant doit allouer cette structure à partir de la mémoire non pagée.

Valeur retournée

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 concerne uniquement les événements personnalisés.

Remarques

Une fois que la routine IoReportTargetDeviceChangeAsynchronous a informé le gestionnaire PnP qu’un événement personnalisé s’est produit sur un appareil, la routine retourne immédiatement ; il n’attend pas que le gestionnaire PnP envoie la 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 IoReportTargetDeviceChangeAsynchronous pour informer le gestionnaire PnP que l’événement personnalisé s’est produit. La notification personnalisée peut être utilisée pour des événements tels qu’un changement d’étiquette de volume.

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 des Uuidgen.exe ou des Guidgen.exe (inclus dans le Microsoft Windows SDK).

Lorsqu’un pilote appelle cette routine lors de la gestion d’un événement, d’un IRP_MN_REMOVE_DEVICE ou d’un IRP_MN_SURPRISE_REMOVAL, le gestionnaire PnP appelle la routine de rappel du pilote après le retour du pilote et le déroulement de la pile.

Les appelants d’IoReportTargetDeviceChangeAsynchronous doivent s’exécuter à IRQL <= DISPATCH_LEVEL. Si un enregistreur de pilotes appelle cette routine à l’adresse IRQL = DISPATCH_LEVEL, la notificationStructure doit être allouée à partir de la mémoire non paginée.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL (voir la section Remarques)
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport)

Voir aussi

IoReportTargetDeviceChange

TARGET_DEVICE_CUSTOM_NOTIFICATION