Freigeben über


WaitCommEvent-Funktion (winbase.h)

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

Siehe auch

Kommunikationsfunktionen

Kommunikationsressourcen

CreateFile

DCB

GetCommMask

GetOverlappedResult

OVERLAPPED

SetCommMask

SetCommState