EVT_SERCX_WAITMASK fonction de rappel (sercx.h)

Article
02/29/2024

La fonction de rappel d’événement EvtSerCxWaitmask configure le contrôleur série pour surveiller les événements dans un masque d’attente, qui est une valeur de masque de bits qui spécifie un ensemble d’événements matériels.

Syntaxe

EVT_SERCX_WAITMASK EvtSercxWaitmask;

NTSTATUS EvtSercxWaitmask(
  [in] WDFDEVICE Device
)
{...}

Paramètres

[in] Device

Un handle WDFDEVICE pour l’objet d’appareil framework qui représente le contrôleur série.

Valeur retournée

La fonction EvtSerCxWaitmask retourne STATUS_SUCCESS si l’appel réussit. Sinon, il retourne une erreur appropriée status code.

Remarques

Le pilote de contrôleur série implémente cette fonction de rappel. L’extension de framework série (SerCx) appelle cette fonction pour avertir le pilote lorsque le masque d’attente change. Pendant cet appel, la fonction EvtSerCxWaitmask appelle la méthode SerCxGetWaitMask pour obtenir le nouveau masque d’attente. Le pilote commence immédiatement à surveiller les événements dans le nouveau masque d’attente et ignore tout ancien masque d’attente qui aurait pu être fourni lors d’un appel EvtSerCxWaitmask précédent. Si le nouveau masque d’attente est égal à zéro, le pilote ignore simplement l’ancien masque d’attente et cesse de surveiller les événements du masque d’attente.

Lorsque SerCx reçoit une requête IOCTL_SERIAL_SET_WAIT_MASK d’un client, le gestionnaire de requêtes dans SerCx appelle la fonction EvtSerCxWaitmask pour définir le nouveau masque d’attente. Pour plus d’informations sur les types d’événements qui peuvent être spécifiés par un masque d’attente, consultez SERIAL_EV_XXX.

La fonction EvtSerCxWaitmask configure le matériel du contrôleur série pour surveiller les événements dans le nouveau masque d’attente. En règle générale, la fonction active les interruptions pour ces événements. Après avoir configuré le matériel, la fonction doit revenir immédiatement, sans attendre qu’un événement dans le masque d’attente se produise.

Plus tard, lorsqu’un événement dans le masque d’attente provoque une interruption, l’ISR du pilote du contrôleur série planifie l’exécution d’une fonction DPC. Cette fonction DPC appelle la méthode SerCxCompleteWait pour notifier SerCx de l’événement.

Initialement, une fois qu’un client a ouvert une connexion au port série et avant le premier appel EvtSerCxWaitmask , le masque d’attente est effectivement zéro et le pilote du contrôleur série ne surveille aucun événement SERIAL_EV_XXX .

Pour inscrire une fonction de rappel EvtSerCxWaitmask , le pilote du contrôleur appelle la méthode SerCxInitialize pendant le rappel EvtDriverDeviceAdd .

Exemples

Le type de fonction de ce rappel est déclaré dans Sercx.h, comme suit.

typedef NTSTATUS
  EVT_SERCX_WAITMASK(
    __in WDFDEVICE Device
    );

Pour définir une fonction de rappel EvtSerCxWaitmask nommée MyEvtSerCxWaitmask, vous devez d’abord fournir une déclaration de fonction requise par Static Driver Verifier (SDV) et d’autres outils de vérification, comme suit.

EVT_SERCX_WAITMASK MyEvtSerCxWaitmask;

Ensuite, implémentez votre fonction de rappel comme suit.

NTSTATUS
  MyEvtSerCxWaitmask(
    __in WDFDEVICE Device
    )
{ ... }

Pour plus d’informations sur les exigences SDV pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes KMDF.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 8.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	sercx.h
IRQL	Appelé à IRQL <= DISPATCH_LEVEL