Fonction IoRegisterContainerNotification (wdm.h)

Article
03/08/2023

La routine IoRegisterContainerNotification inscrit un pilote en mode noyau pour recevoir des notifications sur une classe d’événements spécifiée.

Syntaxe

NTSTATUS
IoRegisterContainerNotification(
    _In_ IO_CONTAINER_NOTIFICATION_CLASS NotificationClass,
    _In_ PIO_CONTAINER_NOTIFICATION_FUNCTION CallbackFunction,
    _In_reads_bytes_opt_(NotificationInformationLength) PVOID NotificationInformation,
    _In_ ULONG NotificationInformationLength,
    _Out_ PVOID * CallbackRegistration
    );

Paramètres

[in] NotificationClass

Spécifie la classe d’événements pour laquelle l’appelant (pilote) demande des notifications. Définissez ce paramètre sur la valeur d’énumération IO_CONTAINER_NOTIFICATION_CLASS suivante :

IoSessionStateNotification

Pour plus d'informations, consultez la section Notes qui suit.

[in] CallbackFunction

Pointeur vers une fonction de rappel implémentée par l’appelant (pilote). Le gestionnaire d’E/S appelle cette fonction pour avertir l’appelant lorsqu’un événement de la classe indiquée par NotificationClass se produit. Pour NotificationClass = IoSessionStateNotification, ce paramètre est un pointeur vers une fonction IO_SESSION_NOTIFICATION_FUNCTION fournie par l’appelant . Toutefois, l’appelant doit convertir ce pointeur de fonction en type PIO_CONTAINER_NOTIFICATION_FUNCTION pour qu’il corresponde au type de paramètre. Pour plus d'informations, consultez la section Notes qui suit.

[in, optional] NotificationInformation

Pointeur vers une mémoire tampon allouée à l’appelant qui contient la structure d’informations de notification pour un événement de la classe spécifiée par NotificationClass. Pour NotificationClass = IoSessionStateNotification, NotificationInformation pointe vers une structure IO_SESSION_STATE_NOTIFICATION . L’appelant doit remplir cette structure avant d’appeler IoRegisterContainerNotification. Pendant cet appel, IoRegisterContainerNotification copie les données de cette structure, et le gestionnaire d’E/S n’accède pas à la copie du pilote de la structure après le retour de l’appel.

[in] NotificationInformationLength

Taille, en octets, de la structure d’informations de notification contenue dans la mémoire tampon pointée par NotificationInformation. Pour NotificationClass = IoSessionStateNotification, définissez ce paramètre sur sizeof(IO_SESSION_STATE_NOTIFICATION).

[out] CallbackRegistration

Pointeur vers un emplacement dans lequel cette routine écrit l’adresse d’un objet d’inscription de notification de conteneur. Cet objet est un objet système opaque dans lequel le gestionnaire d’E/S stocke des informations sur l’inscription des notifications de conteneur de l’appelant. Lorsque les notifications ne sont plus requises, l’appelant annule l’inscription en passant ce pointeur d’objet à la routine IoUnregisterContainerNotification .

Valeur retournée

IoRegisterContainerNotification retourne STATUS_SUCCESS si l’appel réussit. Les valeurs de retour d’erreur possibles sont les suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER_1	Le paramètre NotificationClass n’est pas une constante d’énumération IO_CONTAINER_NOTIFICATION_CLASS valide.
STATUS_INVALID_PARAMETER_3	Les informations de la structure pointées par NotificationInformation sont incorrectes.
STATUS_INVALID_PARAMETER_4	Le paramètre NotificationInformationLength n’est pas égal à la taille de la structure d’informations de notification requise pour une utilisation avec la valeur de paramètre NotificationClass spécifiée.
STATUS_ALREADY_COMMITTED	Le pilote est déjà inscrit pour recevoir des notifications NotificationClass des événements associés à l’objet d’E/S spécifié.
STATUS_INSUFFICIENT_RESOURCES	Le système d’exploitation ne dispose pas de ressources suffisantes pour créer l’inscription demandée.

Remarques

Cette routine peut potentiellement prendre en charge les notifications d’événements dans diverses classes d’événements. Dans Windows 7, cette routine prend uniquement en charge les notifications IoSessionStateNotification, qui informent un pilote en mode noyau des modifications apportées au status des sessions utilisateur qui intéressent le pilote. Pour les applications en mode utilisateur, la fonction WTSRegisterSessionNotification remplit un rôle similaire.

Le type de pointeur de fonction pour le paramètre CallbackFunction est défini comme suit :

typedef NTSTATUS
  (*PIO_CONTAINER_NOTIFICATION_FUNCTION)(
    );

L’appelant doit convertir le pointeur de la fonction de rappel vers ce type pour qu’il corresponde au type de paramètre CallbackFunction . IoRegisterContainerNotification détermine le type réel du pointeur de la fonction de rappel à partir du paramètre NotificationClass . Pour NotificationClass = IoSessionStateNotification, CallbackFunction pointe vers une fonction IO_SESSION_NOTIFICATION_FUNCTION .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows 7 et versions ultérieures du système d’exploitation Windows.
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL