ClearCommError
The ClearCommError
function retrieves information about a communications error and reports the
current status of a communications device. The function is called when a
communications error occurs, and it clears the device s error flag to enable
additional input and output (I/O) operations.
BOOL ClearCommError(
|
HANDLE hFile, |
// handle to communications
device |
|
LPDWORD lpErrors, |
// pointer to
variable to receive error codes |
|
LPCOMSTAT lpStat |
// pointer to
buffer for communications status |
|
); |
|
Parameters
hFile
Identifies
the communications device. The CreateFile function returns this handle.
lpErrors
Points to a
32-bit variable to be filled with a mask indicating the type of error. This
parameter can be one or more of the following error codes:
|
Value |
Meaning |
|
CE_BREAK |
The
hardware detected a break condition. |
|
CE_DNS |
Windows 95
only: A parallel device is not
selected. |
|
CE_FRAME |
The
hardware detected a framing error. |
|
CE_IOE |
An I/O
error occurred during communications with the device. |
|
CE_MODE |
The
requested mode is not supported, or the hFile parameter is invalid. If
this value is specified, it is the only valid error. |
|
CE_OOP |
Windows
95 only: A parallel device signaled
that it is out of paper. |
|
CE_OVERRUN |
A
character-buffer overrun has occurred. The next character is lost. |
|
CE_PTO |
Windows
95 only: A time-out occurred on a
parallel device. |
|
CE_RXOVER |
An input
buffer overflow has occurred. There is either no room in the input buffer, or
a character was received after the end-of-file (EOF) character. |
|
CE_RXPARITY |
The
hardware detected a parity error. |
|
CE_TXFULL |
The
application tried to transmit a character, but the output buffer was full. |
lpStat
Points to a COMSTAT structure in which the
device s status information is returned. If lpStat is NULL, no status
information is returned.
Return Values
If the
function succeeds, the return value is nonzero.
If the
function fails, the return value is zero. To get extended error information,
call GetLastError.
Remarks
If a
communications port has been set up with a TRUE value for the fAbortOnError
member of the setup DCB structure, the communications software will
terminate all read and write operations on the communications port when a
communications error occurs. No new read or write operations will be accepted
until the application acknowledges the communications error by calling the ClearCommError
function.
The ClearCommError
function fills the status buffer pointed to by the lpStat parameter with
the current status of the communications device specified by the hFile
parameter.
See Also