Fonction WaitCommEvent (winbase.h)

Article
08/27/2023

Attend qu’un événement se produise pour un appareil de communication spécifié. L’ensemble d’événements surveillés par cette fonction est contenu dans le masque d’événement associé au handle d’appareil.

Syntaxe

BOOL WaitCommEvent(
  [in]  HANDLE       hFile,
  [out] LPDWORD      lpEvtMask,
  [in]  LPOVERLAPPED lpOverlapped
);

Paramètres

[in] hFile

Handle de l’appareil de communication. La fonction CreateFile retourne ce handle.

[out] lpEvtMask

Pointeur vers une variable qui reçoit un masque indiquant le type d’événement qui s’est produit. Si une erreur se produit, la valeur est zéro ; sinon, il s’agit de l’une des valeurs suivantes.

Valeur	Signification
EV_BREAK 0x0040	Un arrêt a été détecté sur l'entrée.
EV_CTS 0x0008	Le signal CTS (clear-to-send) a changé d’état.
EV_DSR 0x0010	Le signal DSR (data-set-ready) a changé d’état.
EV_ERR 0x0080	Une erreur de status de ligne s’est produite. Les erreurs de status de ligne sont CE_FRAME, CE_OVERRUN et CE_RXPARITY.
EV_RING 0x0100	Un indicateur de tonalité a été détecté.
EV_RLSD 0x0020	L’état du signal RLSD (receive-line-signal-detect) a changé d’état.
EV_RXCHAR 0x0001	Un caractère a été reçu et placé dans la mémoire tampon d’entrée.
EV_RXFLAG 0x0002	Le caractère d’événement a été reçu et placé dans la mémoire tampon d’entrée. Le caractère d’événement est spécifié dans la structure DCB de l’appareil, qui est appliquée à un port série à l’aide de la fonction SetCommState .
EV_TXEMPTY 0x0004	Le dernier caractère de la mémoire tampon de sortie a été envoyé.

[in] lpOverlapped

Pointeur vers une structure OVERLAPPED. Cette structure est requise si hFile a été ouvert avec FILE_FLAG_OVERLAPPED.

Si hFile a été ouvert avec FILE_FLAG_OVERLAPPED, le paramètre lpOverlapped ne doit pas avoir la valeur NULL. Il doit pointer vers une structure CHEVAUCHEMENT VALIDE . Si hFile a été ouvert avec FILE_FLAG_OVERLAPPED et que lpOverlapped a la valeur NULL, la fonction peut signaler à tort que l’opération est terminée.

Si hFile a été ouvert avec FILE_FLAG_OVERLAPPED et que lpOverlapped n’a pas la valeur NULL, WaitCommEvent est effectué en tant qu’opération qui se chevauche. Dans ce cas, la structure OVERLAPPED doit contenir un handle pour un objet d’événement de réinitialisation manuelle (créé à l’aide de la fonction CreateEvent ).

Si hFile n’a pas été ouvert avec FILE_FLAG_OVERLAPPED, WaitCommEvent ne retourne pas l’un des événements spécifiés ou une erreur ne se produit pas.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

La fonction WaitCommEvent surveille un ensemble d’événements pour une ressource de communication spécifiée. Pour définir et interroger le masque d’événement actuel d’une ressource de communication, utilisez les fonctions SetCommMask et GetCommMask .

Si l’opération qui se chevauche ne peut pas être effectuée immédiatement, la fonction retourne FALSE et la fonction GetLastError retourne ERROR_IO_PENDING, ce qui indique que l’opération s’exécute en arrière-plan. Dans ce cas, le système définit le membre hEvent de la structure OVERLAPPED à l’état non signalé avant le retour de WaitCommEvent , puis il le définit à l’état signalé lorsqu’un des événements spécifiés ou une erreur se produit. Le processus appelant peut utiliser l’une des fonctions d’attente pour déterminer l’état de l’objet d’événement, puis utiliser la fonction GetOverlappedResult pour déterminer les résultats de l’opération WaitCommEvent . GetOverlappedResult signale la réussite ou l’échec de l’opération, et la variable pointée par le paramètre lpEvtMask est définie pour indiquer l’événement qui s’est produit.

Si un processus tente de modifier le masque d’événement du handle d’appareil à l’aide de la fonction SetCommMask alors qu’une opération WaitCommEvent superposée est en cours, WaitCommEvent retourne immédiatement. La variable pointée vers par le paramètre lpEvtMask est définie sur zéro.

Exemples

Pour obtenir un exemple, consultez Surveillance des événements de communication.

Configuration requise


Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll