IO_SESSION_NOTIFICATION_FUNCTION fonction de rappel (wdm.h)

Article
03/08/2023

Le type de fonction IO_SESSION_NOTIFICATION_FUNCTION définit une routine de rappel par le biais de laquelle un pilote reçoit des notifications des modifications apportées à l’état des sessions utilisateur qui intéressent le pilote.

Syntaxe

IO_SESSION_NOTIFICATION_FUNCTION IoSessionNotificationFunction;

NTSTATUS IoSessionNotificationFunction(
  [in] PVOID SessionObject,
  [in] PVOID IoObject,
  [in] ULONG Event,
  [in] PVOID Context,
  [in] PVOID NotificationPayload,
  [in] ULONG PayloadLength
)
{...}

Paramètres

[in] SessionObject

Pointeur vers un objet système opaque qui contient des informations sur la session utilisateur. Le pilote peut passer cette valeur de pointeur à la routine IoGetContainerInformation en tant que valeur de paramètre ContainerObject .

[in] IoObject

Pointeur vers un objet d’E/S appartenant au pilote. Ce paramètre est le pointeur d’objet E/S que le pilote a fourni à la routine IoRegisterContainerNotification lorsque le pilote s’est précédemment inscrit pour recevoir des notifications d’événements de session. Le paramètre NotificationInformation de la routine IoRegisterContainerNotification pointe vers une structure IO_SESSION_STATE_NOTIFICATION dont le membre IoObject pointe vers l’objet E/S.

[in] Event

Constante d’énumération IO_SESSION_EVENT qui indique l’événement de session à l’origine du rappel de notification.

[in] Context

Valeur de contexte que le pilote a précédemment fournie à la routine IoRegisterContainerNotification lorsque le pilote s’est inscrit pour recevoir des notifications d’événements de session. Dans l’appel IoRegisterContainerNotification , le pilote a fourni un pointeur vers une structure IO_SESSION_STATE_NOTIFICATION dont le membre Context contient la valeur de contexte.

[in] NotificationPayload

Pointeur vers une mémoire tampon de charge utile qui contient une structure IO_SESSION_CONNECT_INFO .

[in] PayloadLength

Taille, en octets, de la mémoire tampon pointée par NotificationPayload. La taille de la mémoire tampon n’a jamais besoin de dépasser la valeur constante IO_SESSION_MAX_PAYLOAD_SIZE, qui est définie dans le fichier d’en-tête Wdm.h.

Valeur retournée

Si la routine réussit, elle doit retourner STATUS_SUCCESS. Sinon, elle doit retourner l’une des valeurs d’erreur status définies dans le fichier d’en-tête Ntstatus.h.

Remarques

Un pilote en mode noyau implémente cette routine. Le gestionnaire d’E/S appelle cette routine pour avertir le pilote des événements de session.

Pour recevoir des notifications d’événements de session, un pilote appelle la routine IoRegisterContainerNotification et définit le paramètre CallbackFunction de cette routine pour qu’il pointe vers la routine IO_SESSION_NOTIFICATION_FUNCTION du pilote. L’objet d’E/S que le pilote transmet à IoRegisterContainerNotification détermine si le pilote recevra des notifications d’événements dans une session utilisateur particulière ou d’événements dans toutes les sessions. Pour plus d’informations, consultez IO_SESSION_STATE_NOTIFICATION.

Exemples

Pour définir une routine de notification de session d’E/S, 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 notification de session d’E/S nommée MyIoSessionNotification, utilisez le type IO_SESSION_NOTIFICATION_FUNCTION comme indiqué dans cet exemple de code :

IO_SESSION_NOTIFICATION_FUNCTION MyIoSessionNotification;

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

_Use_decl_annotations_
NTSTATUS
  MyIoSessionNotification(
    PVOID  SessionObject,
    PVOID  IoObject,
    ULONG  Event,
    PVOID  Context,
    PVOID  NotificationPayload,
    ULONG  PayloadLength
    )
  {
      // Function body
  }

Le type de fonction IO_SESSION_NOTIFICATION_FUNCTION 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 IO_SESSION_NOTIFICATION_FUNCTION 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
Client minimal pris en charge	Pris en charge dans Windows 7 et versions ultérieures du système d’exploitation Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
IRQL	Appelé à IRQL <= APC_LEVEL.