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 |
|---|---|
|
Bei der Eingabe wurde ein "break" erkannt. |
|
Das CTS-Signal (Clear-to-Send) hat den Zustand geändert. |
|
Das DSR-Signal (Dataset ready) hat den Zustand geändert. |
|
Es ist ein Zeilen-status-Fehler aufgetreten. Line-status-Fehler werden CE_FRAME, CE_OVERRUN und CE_RXPARITY. |
|
Ein Ringindikator wurde erkannt. |
|
Das RLSD-Signal (Receive-line-signal-detect) hat den Zustand geändert. |
|
Ein Zeichen wurde empfangen und im Eingabepuffer platziert. |
|
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. |
|
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 |