EVT_SERCX2_SET_WAIT_MASK fonction de rappel (sercx.h)

Article
10/30/2024

La fonction de rappel d’événements EvtSerCx2SetWaitMask est appelée par la version 2 de l’extension d’infrastructure série (SerCx2) pour configurer le contrôleur série pour 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

Handle WDFDEVICE pour l’objet d’appareil framework qui représente le contrôleur série. Le pilote de 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 requête de framework qui représente la requête IOCTL_SERIAL_SET_WAIT_MASK.

[in] WaitMask

Nouveau masque d’attente. Pour plus d’informations, consultez Remarques.

Valeur de retour

Aucun

Remarques

Votre pilote de contrôleur série peut, en tant qu’option, implémenter cette fonction. S’il est implémenté, le pilote inscrit la fonction dans l’appel à l'SerCx2InitializeDevice méthode qui termine l’initialisation de l’objet d’appareil framework pour le contrôleur série.

Lorsque SerCx reçoit une requête 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 n’est pas 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 peut-être été fourni dans un EvtSerCx2SetWaitMask appel. 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 de 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 le code d’état d’erreur 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 notifier SerCx2 de l’événement.

La fonction EvtSerCx2SetWaitMask est chargée de terminer 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 demande et une valeur d’état pour indiquer si la demande a réussi.

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

Initialement, une fois qu’un client ouvre une connexion logique au port série et avant le premier EvtSerCx2SetWaitMask appel, le masque d’attente est effectivement nul 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 de SERIAL_EV_XXX suivants :

SERIAL_EV_PERR
SERIAL_EV_RING
SERIAL_EV_RXFLAG

Par conséquent, le masque d’attente fourni à votre EvtSerCx2SetWaitMask fonction ne contient jamais d’indicateurs d’événement dans 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 un jeu de données prêt (DSR), la fonction EvtSerCx2SetWaitMask doit prendre en charge SERIAL_EV_DSR. En guise d’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 échouer la requête et définir la valeur d’état dans la requête 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 fonctions de rappel permet d'Analyse du code pour les pilotes, static Driver Verifier (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des 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 illustré 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 lorsque vous exécutez les 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 annoter le comportement de la fonction.