Fungsi WaitCommEvent (winbase.h)

Artikel
08/27/2023

Menunggu peristiwa terjadi untuk perangkat komunikasi tertentu. Kumpulan peristiwa yang dipantau oleh fungsi ini terkandung dalam masker peristiwa yang terkait dengan handel perangkat.

Sintaks

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

Parameter

[in] hFile

Handel ke perangkat komunikasi. Fungsi CreateFile mengembalikan handel ini.

[out] lpEvtMask

Penunjuk ke variabel yang menerima masker yang menunjukkan jenis peristiwa yang terjadi. Jika terjadi kesalahan, nilainya adalah nol; jika tidak, ini adalah salah satu nilai berikut.

Nilai	Makna
EV_BREAK 0x0040	Jeda terdeteksi pada input.
EV_CTS 0x0008	Status perubahan sinyal CTS (clear-to-send).
EV_DSR 0x0010	Status perubahan sinyal DSR (data-set-ready).
EV_ERR 0x0080	Terjadi kesalahan status baris. Kesalahan status baris CE_FRAME, CE_OVERRUN, dan CE_RXPARITY.
EV_RING 0x0100	Indikator cincin terdeteksi.
EV_RLSD 0x0020	Status sinyal RLSD (receive-line-signal-detect) berubah.
EV_RXCHAR 0x0001	Karakter diterima dan ditempatkan di buffer input.
EV_RXFLAG 0x0002	Karakter peristiwa diterima dan ditempatkan di buffer input. Karakter peristiwa ditentukan dalam struktur DCB perangkat, yang diterapkan ke port serial dengan menggunakan fungsi SetCommState .
EV_TXEMPTY 0x0004	Karakter terakhir dalam buffer output dikirim.

[in] lpOverlapped

Penunjuk ke struktur yang TUMPANG TINDIH . Struktur ini diperlukan jika hFile dibuka dengan FILE_FLAG_OVERLAPPED.

Jika hFile dibuka dengan FILE_FLAG_OVERLAPPED, parameter lpOverlapped tidak boleh NULL. Ini harus menunjuk ke struktur TUMPANG TINDIH yang valid. Jika hFile dibuka dengan FILE_FLAG_OVERLAPPED dan lpOverlapped adalah NULL, fungsi dapat salah melaporkan bahwa operasi selesai.

Jika hFile dibuka dengan FILE_FLAG_OVERLAPPED dan lpOverlapped bukan NULL, WaitCommEvent dilakukan sebagai operasi yang tumpang tindih. Dalam hal ini, struktur YANG TUMPANG TINDIH harus berisi handel ke objek peristiwa reset manual (dibuat dengan menggunakan fungsi CreateEvent ).

Jika hFile tidak dibuka dengan FILE_FLAG_OVERLAPPED, WaitCommEvent tidak kembali sampai salah satu peristiwa yang ditentukan atau terjadi kesalahan.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Fungsi WaitCommEvent memantau serangkaian peristiwa untuk sumber daya komunikasi tertentu. Untuk mengatur dan mengkueri masker peristiwa saat ini dari sumber daya komunikasi, gunakan fungsi SetCommMask dan GetCommMask .

Jika operasi yang tumpang tindih tidak dapat segera diselesaikan, fungsi mengembalikan FALSE dan fungsi GetLastError mengembalikan ERROR_IO_PENDING, yang menunjukkan bahwa operasi dijalankan di latar belakang. Ketika ini terjadi, sistem mengatur anggota hEvent dari struktur YANG TUMPANG TINDIH ke status tidak diberi sinyal sebelum WaitCommEvent kembali, dan kemudian mengaturnya ke status yang disinyalir ketika salah satu peristiwa yang ditentukan atau kesalahan terjadi. Proses panggilan dapat menggunakan salah satu fungsi tunggu untuk menentukan status objek peristiwa lalu menggunakan fungsi GetOverlappedResult untuk menentukan hasil operasi WaitCommEvent . GetOverlappedResult melaporkan keberhasilan atau kegagalan operasi, dan variabel yang ditunjukkan oleh parameter lpEvtMask diatur untuk menunjukkan peristiwa yang terjadi.

Jika proses mencoba mengubah masker peristiwa handel perangkat dengan menggunakan fungsi SetCommMask saat operasi WaitCommEvent yang tumpang tindih sedang berlangsung, WaitCommEvent akan segera kembali. Variabel yang diacu oleh parameter lpEvtMask diatur ke nol.

Contoh

Misalnya, lihat Memantau Peristiwa Komunikasi.

Persyaratan


Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll