| BOOL SetCommTimeouts(hCommDev, lpct) | |||||
| HANDLE hCommDev; | /* specifies device to set | */ | |||
| LPCOMMTIMEOUTS lpct; | /* timeout times to set | */ | |||
The SetCommTimeouts function sets the timeout characteristics for all read and write operations on the specified communications device.
hCommDev
Specifies the communication device to set the timeouts for. The CreateFile function returns this value.
lpct
Points to a COMMTIMEOUTS structure which is used to set the current communications timeouts.
The COMMTIMEOUTS structure has the following form:
typedef struct _COMMTIMEOUTS { /* ctmo */
DWORD ReadIntervalTimeout;
DWORD ReadTotalTimeoutMultiplier;
DWORD ReadTotalTimeoutConstant;
DWORD WriteTotalTimeoutMultiplier;
DWORD WriteTotalTimeoutConstant;
} COMMTIMEOUTS,*LPCOMMTIMEOUTS;
The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.
The total timer starts immediately. The interval timer is not started until the first character is received.
The behavior of this function can be controlled by varying the timeout parameters. See the table below for details. Timeouts are specified in milliseconds, accurate to the granularity of the Win32 free-running millisecond counter. If a timeout occurs, the count of characters successfully read or written is indicated by the ReadFile or WriteFile function.
The SetupComm function automatically initializes all timeout parameters to zero.
The TotalTimeout in milliseconds for each ReadFile and WriteFile operation is computed as follows:
TotalTimeout = m * n + k where:
| Value | Meaning |
| m | multiplier (lpct->dwReadTotalTimeoutMultiplier or lpct->dwWriteTotalTimeoutMultiplier) |
| n | number of characters in I/O operation |
| k | constant (lpct->dwReadTotalTimeoutConstant or lpct->dwWriteTotalTimeoutConstant) |
The following table summarizes the behavior of I/O operations based on the specified timeouts.
| TotalTimeout | dwIntervalTimeout | Meaning |
| 0 | 0 | Return when buffer is completely filled. The timeouts are not used. |
| T | 0 | Fill buffer until T milliseconds have expired or the buffer is completely filled. This timer starts immediately. |
| 0 | Y | Return if Y or more milliseconds elapse between any two characters received or the buffer is completely filled. This timer is started when the first character is received. |
| T | Y | Return as soon as either timer expires or the buffer is completely filled, whichever occurs first. |
Note that timing is relative to the system controlling the physical device. For a remote device such as a modem, the timing is relative to the server system to which the modem is attached. Any network propagation delay is not factored in. For example, a client application might specify a total timeout which computes to be 500 ms. When 500 ms has elapsed at the server, a timeout error is returned to the client. If there is a 50 ms network propagation delay, then the client will not be notified of timeout until approximately 50 ms after the timeout actually occurred.