serial programming-Configuring Timeouts

							Configuring Timeouts

An application must always set communication timeouts using the COMMTIMEOUTS structure
each time it opens a communication port.

If this structure is not configured, the port uses default timeouts supplied by the driver, or
timeouts from a previous communication application.

By assuming specific timeout settings when the settings are actually different, an application can
have read/write operations that never complete or complete too often.

When read/write operations time out, the operations complete with no error values returned to
the ReadFile and WriteFile functions.

To determine if an operation has timed out, verify that the number of bytes transferred is fewer
than the number of bytes requested.

For example, if the ReadFile function returns TRUE, but fewer bytes were read than requested,
the operation has timed out.

To configure timeouts for a serial port

   1. Initialize the COMMITEMEOUTS structure by calling the GetCommTimeouts function
      or by setting the members manually.
   2. Specify the maximum number of milliseconds that can elapse between two characters
      without a timeout occurring with the ReadIntervalTimeout member.
   3. Specify the read timeout multiplier with the ReadTotalTimeoutMultiplier member.

       For each read operation, this number is multiplied by the number of bytes that the read
       operation expects to receive.

   4. Specify the read timeout constant with the ReadTotalTimeoutConstant member.

       This member is the number of milliseconds added to the result of multiplying the total
       number of bytes to read by ReadTotalTimeoutMultiplier.

       The result is the number of milliseconds that must elapse before a timeout for the read
       operation occurs.

   5. Specify the write timeout multiplier with the WriteTotalTimeoutMultiplier member.

       For each write operation, this number is multiplied by the number of bytes that the write
       operation expects to receive.
   6. Specify the write timeout constant with the WriteTotalTimeoutConstant member.

       This member is the number of milliseconds added to the result of multiplying the total
       number of bytes to write by WriteTotalTimeoutMultiplier.

       The result is the number of milliseconds that must elapse before a timeout for the write
       operation occurs.

   7. Call the SetCommTimeouts function to activate port timeout settings.

       Note Because there are two timeouts, interval timeout and (total timeout constant + total
       timeout multiplier * number of bytes), an actual timeout is whichever timeout occurs
       first.

To assist with multitasking, it is common to configure COMMTIMEOUT so ReadFile
immediately returns with all characters in the input buffer. To do this, set ReadIntervalTimeout
to MAXWORD and set both ReadTotalTimeoutMultiplier and ReadTotalTimeoutConstant
to zero.

The following code example shows how to configure timeouts for a serial port.

// Retrieve the timeout parameters for all read and write operations
// on the port.
COMMTIMEOUTS CommTimeouts;
GetCommTimeouts (hPort, &CommTimeouts);

// Change the COMMTIMEOUTS structure settings.
CommTimeouts.ReadIntervalTimeout = MAXDWORD;
CommTimeouts.ReadTotalTimeoutMultiplier = 0;
CommTimeouts.ReadTotalTimeoutConstant = 0;
CommTimeouts.WriteTotalTimeoutMultiplier = 10;
CommTimeouts.WriteTotalTimeoutConstant = 1000;

// Set the timeout parameters for all read and write operations
// on the port.
if (!SetCommTimeouts (hPort, &CommTimeouts))
{
  // Could not set the timeout parameters.
  MessageBox (hMainWnd, TEXT("Unable to set the timeout parameters"),
              TEXT("Error"), MB_OK);
  dwError = GetLastError ();
  return FALSE;
}