ReadFile is used to read from an open device, using a handle to a communications resource as returned from CreateFile. This can support several different read operations depending on the settings of the timeout values and the handle's overlapped flag. The timeout values are set when the device is opened according to the values set when the device was last opened. If the device has never been opened, all total and interval timeouts are set to 0. To determine the current timeout values, call GetCommTimeouts. The timeout values can be changed by calling SetCommTimeouts.
| blocking | ReadFile does not return until the requested number of bytes have been read. This occurs if all total and interval timeout values are set to 0, and overlapped I/O is not enabled. |
| non-blocking | ReadFile returns immediately with whatever is available in the receive queue (even if it is empty), and indicates the actual number of bytes read. This is the same behavior as the ReadComm function in previous versions of Windows. Non-blocking reads occur if SetCommTimeouts has been called with an interval timeout of INFINITE and both total timeout parameters equal to zero. |
| interval timeout | An interval timeout occurs when the interval between the arrival of two characters exceeds a specified maximum. Timing does not begin until the first character has been received, which makes this type of timeout useful in implementing a wait-for-something read. If the interval value is zero, interval timing is not used. Interval timing is designed to force a read to return when there is a lull in the reception. An application using interval timeouts can set a fairly short timeout interval so that it can respond quickly to small, isolated bursts of one or a few characters, and yet still collect large buffers of characters with a single call when data is being received in a steady stream. |
| total timeout | A total timeout occurs when the total time for a read operation exceeds a calculated time period. Timing begins immediately. A constant and a multiplier specified in SetCommTimeouts are used together to calculate the total timeout period as follows: constant + (multiplier * bytes requested) |
| This allows an application to set a total timeout that varies depending on the amount of data being requested. You may use just the constant by setting the multiplier to zero; or just the multiplier by setting the constant to zero. If both are zero, total timing is not used. | |
| overlapped | Overlapped I/O can be enabled when CreateFile is called to open a device handle. If the specified number of characters can be read immediately, or if non-blocking reading has been enabled as described above, ReadFile will return TRUE. Otherwise, it will return FALSE and GetLastError will indicate ERROR_IO_PENDING, as the read completes in the background. The Event object in the OVERLAPPED structure (or the device handle if the Event object is NULL) will be signalled when the read is complete. Either of the wait functions, WaitForMultipleObjects or WaitForSingleObject, can be used to wait for the Event object or the file handle to be signalled. When this happens, call GetOverlappedResult to determine the number of bytes read. The timeout values are still used in conjunction with overlapped I/O to determine when the read is complete. Overlapped I/O allows an application to do more than one I/O operation at a time. For example, you could read from two or more devices simultaneously, read from one device while writing to another, or read and write from one device at the same time. |
If a timeout occurs, ReadFile returns TRUE (a successful read) and indicates the number of characters read prior to the timeout. It is possible to use both interval and total timing, in which case, ReadFile will return when either one times out.
There are a few other circumstances where a ReadFile call can return with fewer than the requested number of characters, even though a timeout has not occurred. Some providers support the use of special characters which when received, cause ReadFile to return immediately with characters read to that point. It is also possible to abort a read operation by calling the PurgeComm function which deletes the contents of the transmit or receive queue (or both), or can be made to abort pending read or write operations. If PurgeComm(PURGE_RXABORT) is called during a read operation, ReadFile will return FALSE and GetLastError will return ERROR_OPERATION_ABORTED.
If a communication error occurs during a read, all operations will abort. For example, if a break condition is detected, or a parity or framing error occurs, ReadFile will return FALSE and the contents of its buffer are not valid. Call ClearCommError to determine the specific error and the current status of the device. ClearCommError also clears the error flag to allow additional I/O operations to be made.