Funzione WaitCommEvent (winbase.h)

Articolo
08/27/2023

Attende che si verifichi un evento per un dispositivo di comunicazione specificato. Il set di eventi monitorati da questa funzione è contenuto nella maschera eventi associata all'handle del dispositivo.

Sintassi

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

Parametri

[in] hFile

Handle per il dispositivo di comunicazione. La funzione CreateFile restituisce questo handle.

[out] lpEvtMask

Puntatore a una variabile che riceve una maschera che indica il tipo di evento che si è verificato. Se si verifica un errore, il valore è zero; in caso contrario, è uno dei valori seguenti.

Valore	Significato
EV_BREAK 0x0040	È stata rilevata un'interruzione nell'input.
EV_CTS 0x0008	Lo stato del segnale CTS (clear-to-send) è cambiato.
EV_DSR 0x0010	Lo stato del segnale DSR (data-set-ready) è stato modificato.
EV_ERR 0x0080	Si è verificato un errore di stato della riga. Gli errori di stato riga sono CE_FRAME, CE_OVERRUN e CE_RXPARITY.
EV_RING 0x0100	È stato rilevato un indicatore sonoro.
EV_RLSD 0x0020	Lo stato del segnale RLSD (receive-line-signal-detect) è cambiato.
EV_RXCHAR 0x0001	È stato ricevuto un carattere ed è stato collocato nel buffer di input.
EV_RXFLAG 0x0002	Il carattere dell'evento è stato ricevuto e inserito nel buffer di input. Il carattere di evento viene specificato nella struttura DCB del dispositivo, che viene applicata a una porta seriale usando la funzione SetCommState .
EV_TXEMPTY 0x0004	Ultimo carattere nel buffer di output inviato.

[in] lpOverlapped

Puntatore a una struttura OVERLAPPED . Questa struttura è necessaria se hFile è stato aperto con FILE_FLAG_OVERLAPPED.

Se hFile è stato aperto con FILE_FLAG_OVERLAPPED, il parametro lpOverlapped non deve essere NULL. Deve puntare a una struttura OVERLAPPED valida. Se hFile è stato aperto con FILE_FLAG_OVERLAPPED e lpOverlapped è NULL, la funzione può segnalare erroneamente che l'operazione è stata completata.

Se hFile è stato aperto con FILE_FLAG_OVERLAPPED e lpOverlapped non è NULL, WaitCommEvent viene eseguito come operazione sovrapposta. In questo caso, la struttura OVERLAPPED deve contenere un handle per un oggetto evento di reimpostazione manuale (creato tramite la funzione CreateEvent ).

Se hFile non è stato aperto con FILE_FLAG_OVERLAPPED, WaitCommEvent non restituisce finché non si verifica uno degli eventi specificati o un errore.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

La funzione WaitCommEvent monitora un set di eventi per una risorsa di comunicazione specificata. Per impostare ed eseguire query sulla maschera eventi corrente di una risorsa di comunicazione, usare le funzioni SetCommMask e GetCommMask .

Se l'operazione sovrapposta non può essere completata immediatamente, la funzione restituisce FALSE e la funzione GetLastError restituisce ERROR_IO_PENDING, a indicare che l'operazione è in esecuzione in background. In questo caso, il sistema imposta il membro hEvent della struttura OVERLAPPED sullo stato non segnalato prima che WaitCommEvent restituisca e quindi lo imposta sullo stato segnalato quando si verifica uno degli eventi specificati o un errore. Il processo chiamante può utilizzare una delle funzioni di attesa per determinare lo stato dell'oggetto evento e quindi utilizzare la funzione GetOverlappedResult per determinare i risultati dell'operazione WaitCommEvent . GetOverlappedResult segnala l'esito positivo o negativo dell'operazione e la variabile a cui punta il parametro lpEvtMask viene impostata per indicare l'evento che si è verificato.

Se un processo tenta di modificare la maschera evento dell'handle del dispositivo usando la funzione SetCommMask mentre è in corso un'operazione WaitCommEvent sovrapposta, WaitCommEvent restituisce immediatamente. La variabile a cui punta il parametro lpEvtMask è impostata su zero.

Esempio

Per un esempio, vedere Monitoraggio degli eventi di comunicazione.

Requisiti


Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll