Waits for an event to occur for a specified communications device. The set of events that are monitored by this function is contained in the event mask associated with the device handle.
If hFile was opened with FILE_FLAG_OVERLAPPED, the lpOverlapped parameter must not be NULL. It must point to a valid OVERLAPPED structure. If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function can incorrectly report that the operation is complete.
If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, WaitCommEvent is performed as an overlapped operation. In this case, the OVERLAPPED structure must contain a handle to a manual-reset event object (created by using the CreateEvent function).
If hFile was not opened with FILE_FLAG_OVERLAPPED, WaitCommEvent does not return until one of the specified events or an error occurs.
CommentsIf an overlapped structure is passed, then the PyOVERLAPPED::dword address is passed to the Win32 API as the mask. This means that once the overlapped operation has completed, this dword attribute can be used to determine the type of event that occurred.
Return ValueThe result is a tuple of (rc, mask_val), where rc is zero for success, or the result of calling GetLastError() otherwise. The mask_val is the new mask value once the function has returned, but if an Overlapped object is passed, this value will generally be meaningless. See the comments for more details.