28.2.5 Writing to a Communications Resource

WriteFile is used to write to an open device, using a handle to a communications resource as returned from CreateFile. As with ReadFile, the behavior of WriteFile depends on the timeout values set by calling SetCommTimeouts, and the handle's overlapped flag which is set when the device is opened by CreateFile. The default behavior of WriteFile is to not use timeouts. If overlapped I/O is not enabled and timeouts are not used, WriteFile will block until the specified number of characters have been transmitted. A write can block if some kind of flow control is occurring or if SetCommBreak is called to suspend character transmission.

The two timeout values for WriteFile, WriteTotalTimeoutMultiplier and WriteTotalTimeoutConstant, are used to calculate a total timeout period in the same way as calculated for read operations. Interval timeouts are not provided for write operations. If a timeout occurs, WriteFile returns TRUE and the number of characters actually transmitted is returned.

TransmitCommChar sends a character to the head of transmit queue. This is useful in transmitting a high priority signal character to the receiving system. Transmission is still subject to flow control and write timeouts, and the operation is performed synchronously.

If PurgeComm is called to purge a transmit queue, the deleted characters will not be transmitted. To empty the transmit queue while ensuring that the contents are transmitted, call FlushFileBuffers (which is a synchronous operation). Note that FlushFileBuffers is subject to flow control but not to write timeouts, and it will not return until all pending writes have been transmitted.

If a communication error occurs while writing to a communications device, the write operation will abort. Call ClearCommError to determine the current status of the device and a code indicating the specific error. This call clears the error flag to allow additional read or write calls to be made.