Bug in Win32file WaitCommEvent ???

[Bengt Richter]

On Tue, 19 Nov 2002 22:17:03 GMT, Mark Hammond <mhammond at skippinet.com.au> wrote:

>Grant Edwards wrote:
>> I'm trying to figure out how WaitCommEvent() works in Python,
>> and it looks like there's a problem when it's used in
>> overlapped mode.
>> 
>> My understanding is that (in C) you:
>> 
>>  1) Call WaitCommEvent() and give it three parameters:
>>      * File handle
>>      * a pointer to where the output mask value is to be stored
>>      * a pointer to an overlapped struct
>>     
>>  2) WaitCommEvent() returns immediately.
>> 
>>  3) Call one of the WaitXXX() functions to wait on the event in
>>     the overloapped struct.
>> 
>>  4) When the event is triggered WaitXXX() returns. Check the
>>     value stored via the output mask pointer passed in 1)
>>     above.
>> 
>> [I've gleaned most of this from
>> http://msdn.microsoft.com/library/en-us/devio/base/waitcommevent.asp]
>
>I don't think this last step is correct.  Certainly the link you posted 
>doesn't say this is true.  Looking further, I can't find *anything* that 
>implies this is true.
>
>KB Q175551 has sample code for Windows CE that uses overlapped IO, and 
>it examines the mask immediately after the call.
>
>Further, if what you say is correct, I would expect Python COM port 
>based programs to regularly crash!  In your scenario, by the time the 
>overlapped function ended up writing to our mask variable, that address 
>would be invalid.  However, it would be pretty close to the top of the 
>stack, so I would expect it to corrupt whatever was running when the 
>mask was actually written.  I know a number of people have used these 
>APIs to do serious serial port control - either directly, or via another 
>wrapper.  I would be very surprised we survived this long.
>
>Can you find an explicit reference to this?
>
>Mark.
>
==== from an old win32 help file that may have come with an old version of Delphi ?? ======

The WaitCommEvent function 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. 

BOOL WaitCommEvent(
    HANDLE  hCommDev,       // handle of communications device
    LPDWORD  lpfdwEvtMask,  // address of variable for event that occurred  
    LPOVERLAPPED  lpo,      // address of overlapped structure
);	


Parameters
hCommDev
  Identifies the communications device. The CreateFile function returns this handle. 

lpfdwEvtMask
  Points to a 32-bit variable that receives a mask indicating the
  type of event that occurred. If an error occurs, the value is zero;
  otherwise, it is one of the following values: 

Value          Meaning
EV_BREAK       A break was detected on input.
EV_CTS         The CTS (clear-to-send) signal changed state.
EV_DSR         The DSR (data-set-ready) signal changed state.
EV_ERR         A line-status error occurred. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY.
EV_RING        A ring indicator was detected.
EV_RLSD        The RLSD (receive-line-signal-detect) signal changed state.
EV_RXCHAR      A character was received and placed in the input buffer.
EV_RXFLAG      The event character was received and placed in the input buffer.
                 The event character is specified in the device's DCB structure,
                 which is applied to a serial port by using the SetCommState function.
EV_TXEMPTY     The last character in the output buffer was sent.


lpo
  Points to an OVERLAPPED structure. This parameter is ignored if the hCommDev
  handle was opened without specifying the FILE_FLAG_OVERLAPPED flag.
  If an overlapped operation is not desired, this parameter can be NULL. 

Return Value
  If the function succeeds, the return value is TRUE.
  If the function fails, the return value is FALSE. To get extended error information, call GetLastError. 

Remarks
  The WaitCommEvent function monitors a set of events for a specified
    communications resource. To set and query the current event mask of a communications resource,
    use the SetCommMask and GetCommMask functions. 

  If the lpo parameter is NULL or the hCommDev handle was opened without specifying
    the FILE_FLAG_OVERLAPPED flag, WaitCommEvent does not return until one of the specified
    events or an error occurs. 

  If lpo points to an OVERLAPPED structure and FILE_FLAG_OVERLAPPED was specified when the
    hCommDev handle was opened, 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 the overlapped operation cannot be completed immediately, the function returns FALSE and
    the GetLastError function returns ERROR_IO_PENDING, indicating that the operation is executing
    in the background. When this happens, the system sets the hEvent member of the OVERLAPPED
    structure to the not-signaled state before WaitCommEvent returns, and then it sets it to the
    signaled state when one of the specified events or an error occurs. The calling process can
                                                                        ^^^^^^^^^^^^^^^^^^^^^^^ 
    use a wait function to determine the event object's state and then use the GetOverlappedResult
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    function to determine the results of the WaitCommEvent operation. GetOverlappedResult reports
                                                                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^
    the success or failure of the operation, and the variable pointed to by the lpfdwEvtMask
                                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    parameter is set to indicate the event that occurred. 
    ^^^^^^^^^^^^^^^^

  If a process attempts to change the device handle's event mask by using the SetCommMask
    function while an overlapped WaitCommEvent operation is in progress, WaitCommEvent returns
    immediately. The variable pointed to by the lpfdwEvtMask parameter is set to zero. 

See Also
  CreateFile, DCB, GetCommMask, GetOverlappedResult, OVERLAPPED, SetCommMask, SetCommState 

==========================================

Sounds like the mask location is safe if you don't call GetOverlappedResult ??


Regards,
Bengt Richter