EVT_SERCX2_SET_WAIT_MASK fonction de rappel (sercx.h)

Article
02/29/2024

La fonction de rappel d’événement EvtSerCx2SetWaitMask est appelée par la version 2 de l’extension d’infrastructure série (SerCx2) pour configurer le contrôleur série afin de surveiller un ensemble d’événements matériels spécifiés par un masque d’attente.

Syntaxe

EVT_SERCX2_SET_WAIT_MASK EvtSercx2SetWaitMask;

void EvtSercx2SetWaitMask(
  [in] WDFDEVICE Device,
  [in] WDFREQUEST Request,
  [in] ULONG WaitMask
)
{...}

Paramètres

[in] Device

Un handle WDFDEVICE pour l’objet d’appareil framework qui représente le contrôleur série. Le pilote du contrôleur série a créé cet objet dans sa fonction de rappel EvtDriverDeviceAdd . Pour plus d’informations, consultez SerCx2InitializeDevice.

[in] Request

Handle WDFREQUEST pour l’objet de demande d’infrastructure qui représente la demande IOCTL_SERIAL_SET_WAIT_MASK .

[in] WaitMask

Nouveau masque d’attente. Pour plus d'informations, consultez la section Notes.

Valeur de retour

None

Remarques

Votre pilote de contrôleur série peut, en option, implémenter cette fonction. En cas d’implémentation, le pilote inscrit la fonction dans l’appel à la méthode SerCx2InitializeDevice qui termine l’initialisation de l’objet de périphérique d’infrastructure pour le contrôleur série.

Lorsque SerCx reçoit une demande IOCTL_SERIAL_SET_WAIT_MASK d’un client, le gestionnaire de requêtes dans SerCx2 appelle la fonction EvtSerCx2SetWaitMask , si elle est implémentée, pour avertir le pilote que le masque d’attente a changé. Si le masque d’attente est différent de zéro, le pilote commence immédiatement à surveiller les événements dans le nouveau masque d’attente et ignore tout ancien masque d’attente qui a pu être fourni dans un appel EvtSerCx2SetWaitMask précédent. Si le nouveau masque d’attente est égal à zéro, le pilote abandonne simplement l’ancien masque d’attente et cesse de surveiller les événements du 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.

Si le pilote n’implémente pas cette fonction, SerCx2 échoue toutes les requêtes IOCTL_SERIAL_SET_WAIT_MASK avec une erreur status code STATUS_NOT_SUPPORTED.

Pour surveiller les événements dans le masque d’attente, la fonction EvtSerCx2SetWaitMask active généralement les interruptions pour ces événements. Plus tard, lorsqu’un événement dans le masque d’attente est détecté, le pilote du contrôleur série appelle la méthode SerCx2CompleteWait pour informer SerCx2 de l’événement.

La fonction EvtSerCx2SetWaitMask est chargée d’effectuer la requête IOCTL_SERIAL_SET_WAIT_MASK pointée par le paramètre Request . Une fois que le pilote du contrôleur série a activé les interruptions nécessaires, il appelle la méthode WdfRequestComplete et fournit, en tant que paramètres d’entrée, la valeur du paramètre Request et une valeur de status pour indiquer si la demande a réussi.

Avant que le pilote du contrôleur série appelle WdfRequestComplete pour terminer la demande, le pilote doit terminer tous les appels à SerCx2CompleteWait qui peuvent être toujours en attente en raison d’événements dans l’ancien masque d’attente.

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

SerCx2 échoue à une demande de IOCTL_SERIAL_SET_WAIT_MASK qui a un masque d’attente qui inclut l’un des indicateurs d’événement SERIAL_EV_XXX suivants :

SERIAL_EV_PERR
SERIAL_EV_RING
SERIAL_EV_RXFLAG

Ainsi, le masque d’attente fourni à votre fonction EvtSerCx2SetWaitMask ne contient jamais les indicateurs d’événement de la liste précédente.

Si elle est implémentée, votre fonction EvtSerCx2SetWaitMask doit prendre en charge les indicateurs d’événement suivants :

SERIAL_EV_CTS
SERIAL_EV_BREAK
SERIAL_EV_ERR

En outre, si le contrôleur série a une ligne de signal prêt pour le jeu de données (DSR), la fonction EvtSerCx2SetWaitMask doit prendre en charge SERIAL_EV_DSR. En option, un pilote peut prendre en charge l’un des autres indicateurs d’événement décrits dans SERIAL_EV_XXX. Si le masque d’attente spécifie un événement que le pilote ne prend pas en charge, la fonction EvtSerCx2SetWaitMask doit faire échouer la requête et définir la valeur status dans la demande sur STATUS_INVALID_PARAMETER.

Exemples

Pour définir une fonction de rappel EvtSerCx2SetWaitMask , vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction 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 fonction de rappel EvtSerCx2SetWaitMask nommée MySetWaitmask, utilisez le type de fonction EVT_SERCX2_SET_WAIT_MASK , comme indiqué dans cet exemple de code :

EVT_SERCX2_SET_WAIT_MASK  MySetWaitmask;

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

_Use_decl_annotations_
VOID
  MySetWaitmask(
    WDFDEVICE  Device,
    WDFREQUEST Request,
    ULONG WaitMask
    )
  {...}

Le type de fonction EVT_SERCX2_SET_WAIT_MASK est défini dans le fichier d’en-tête Sercx.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 EVT_SERCX2_SET_WAIT_MASK 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 KMDF. Pour plus d’informations sur Use_decl_annotations, consultez Annotating Function Behavior.

Configuration requise

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