WaitCommEvent-Funktion (winbase.h)

Artikel
08/27/2023

Wartet, bis ein Ereignis für ein angegebenes Kommunikationsgerät auftritt. Der Satz von Ereignissen, die von dieser Funktion überwacht werden, ist in der Ereignismaske enthalten, die dem Gerätehandle zugeordnet ist.

Syntax

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

Parameter

[in] hFile

Ein Handle für das Kommunikationsgerät. Die CreateFile-Funktion gibt dieses Handle zurück.

[out] lpEvtMask

Ein Zeiger auf eine Variable, die eine Maske empfängt, die den Typ des aufgetretenen Ereignisses angibt. Wenn ein Fehler auftritt, ist der Wert null; Andernfalls handelt es sich um einen der folgenden Werte.

Wert	Bedeutung
EV_BREAK 0x0040	Bei der Eingabe wurde ein "break" erkannt.
EV_CTS 0x0008	Das CTS-Signal (Clear-to-Send) hat den Zustand geändert.
EV_DSR 0x0010	Das DSR-Signal (Dataset ready) hat den Zustand geändert.
EV_ERR 0x0080	Es ist ein Zeilen-status-Fehler aufgetreten. Line-status-Fehler werden CE_FRAME, CE_OVERRUN und CE_RXPARITY.
EV_RING 0x0100	Ein Ringindikator wurde erkannt.
EV_RLSD 0x0020	Das RLSD-Signal (Receive-line-signal-detect) hat den Zustand geändert.
EV_RXCHAR 0x0001	Ein Zeichen wurde empfangen und im Eingabepuffer platziert.
EV_RXFLAG 0x0002	Das Ereigniszeichen wurde empfangen und im Eingabepuffer platziert. Das Ereigniszeichen wird in der DCB-Struktur des Geräts angegeben, die mithilfe der SetCommState-Funktion auf einen seriellen Port angewendet wird.
EV_TXEMPTY 0x0004	Das letzte Zeichen im Ausgabepuffer wurde gesendet.

[in] lpOverlapped

Ein Zeiger auf eine Struktur OVERLAPPED. Diese Struktur ist erforderlich, wenn hFile mit FILE_FLAG_OVERLAPPED geöffnet wurde.

Wenn hFile mit FILE_FLAG_OVERLAPPED geöffnet wurde, darf der lpOverlapped-Parameter nicht NULL sein. Sie muss auf eine gültige OVERLAPPED-Struktur verweisen. Wenn hFile mit FILE_FLAG_OVERLAPPED geöffnet wurde und lpOverlappedNULL ist, kann die Funktion fälschlicherweise melden, dass der Vorgang abgeschlossen ist.

Wenn hFile mit FILE_FLAG_OVERLAPPED geöffnet wurde und lpOverlapped nicht NULL ist, wird WaitCommEvent als überlappender Vorgang ausgeführt. In diesem Fall muss die OVERLAPPED-Struktur ein Handle für ein Ereignisobjekt mit manueller Zurücksetzung (erstellt mit der CreateEvent-Funktion ) enthalten.

Wenn hFile nicht mit FILE_FLAG_OVERLAPPED geöffnet wurde, wird WaitCommEvent erst zurückgegeben, wenn eines der angegebenen Ereignisse oder ein Fehler auftritt.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die WaitCommEvent-Funktion überwacht eine Reihe von Ereignissen für eine angegebene Kommunikationsressource. Verwenden Sie die Funktionen SetCommMask und GetCommMask , um die aktuelle Ereignismaske einer Kommunikationsressource festzulegen und abzufragen.

Wenn der überlappende Vorgang nicht sofort abgeschlossen werden kann, gibt die Funktion FALSE zurück, und die GetLastError-Funktion gibt ERROR_IO_PENDING zurück, was angibt, dass der Vorgang im Hintergrund ausgeführt wird. In diesem Fall legt das System den hEvent-Member der OVERLAPPED-Struktur auf den nicht signalierten Zustand fest, bevor WaitCommEvent zurückgibt, und legt ihn dann auf den signalierten Zustand fest, wenn eines der angegebenen Ereignisse oder ein Fehler auftritt. Der aufrufende Prozess kann eine der Wartefunktionen verwenden, um den Zustand des Ereignisobjekts zu bestimmen, und dann die GetOverlappedResult-Funktion verwenden, um die Ergebnisse des WaitCommEvent-Vorgangs zu bestimmen. GetOverlappedResult meldet den Erfolg oder Fehler des Vorgangs, und die Variable, auf die der lpEvtMask-Parameter verweist, wird festgelegt, um das aufgetretene Ereignis anzugeben.

Wenn ein Prozess versucht, die Ereignismaske des Gerätehandles mithilfe der SetCommMask-Funktion zu ändern, während ein überlappender WaitCommEvent-Vorgang ausgeführt wird, wird WaitCommEvent sofort zurückgegeben. Die Variable, auf die der parameter lpEvtMask verweist, wird auf null festgelegt.

Beispiele

Ein Beispiel finden Sie unter Überwachen von Kommunikationsereignissen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll