Win32 API provides WaitCommEvent function used to wait for events which can occur for the specified communications device. At that the set of events checked by this function is contained in the events mask connected with the given device.
BOOL WaitCommEvent(HANDLE hFile, LPDWORD lpEvtMask, LPOVERLAPPED lpOverlapped);
hFile — the descriptor of the open file of the communication port;
lpEvtMask - pointer to a 32-bit variable which receives the mask specifying the type of event occurred. If an error occurs, null-value is returned, if the result is successful, one of the following values is returned:
lpOverlapped - pointer to the OVERLAPPED structure. This structure is needed if hFile was opened with the help of FILE_FLAG_OVERLAPPED.
If hFile was opened with the help of FILE_FLAG_OVERLAPPED, lpOverlapped parameter shouldn't be NULL. This pointer should point at the active OVERLAPPED structure. If hFile was opened with the help of FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, WaitCommEvent function is executed as an overlapped operation. In this case the OVERLAPPED structure should contain a descriptor to a manual-reset event object (created by using the CreateEvent function).
If hFile descriptor wasn't opened with the help of FILE_FLAG_OVERLAPPED, WaitCommEvent is not returned until one of the specified events (or an error) occurs.
WaitCommEvent controls the events set for the specified connection resource. Use SetCommMask and GetCommMask functions to set and get a mask of the current eventfor the connection device.
If an overlapped operation cannot be stopped immediately the function returns FALSE and GetLastError function returns ERROR_IO_PENDING, by that indicating that an operation is being executed in the background. When it happens the system sets the hEvent member of the OVERLAPPED structure into not-signaled state until WaitCommEvent is returned, and then it sets it to the signaled state when one of the specified events (or an error) occurs. The request process can use one of the wait functions to detect the state of the event objects and then use GetOverlappedResult function to detect the WaitCommEvent operation result. GetOverlappedResult reports of a sucsessful or unsuccessful operation result, at the same time the transient pointer at lpEvtMask parameter is set to indicate the event occurred.
If the process is trying to change the event mask of the device descriptor by using the SetCommMask function while the overlapped WaitCommEvent operation is being executed, WaitCommEvent is immediately returned. The pointer of the lpEvtMask parameter variable is set to zero.
fCoder © 1998 - 2002