IOCTL_SERIAL_PURGE control code
The IOCTL_SERIAL_PURGE request cancels the specified requests and deletes data from the specified buffers. The purge request can be used to cancel all read requests and write requests and to delete all data from the receive buffer and the transmit buffer.
The completion of the purge request does not indicate that the requests canceled by the purge request are completed. A client must verify that the purged requests are completed before the client frees or reuses the corresponding IRPs.
The AssociatedIrp.SystemBuffer member points to a client-allocated ULONG that is used to input a purge mask. The client sets the purge mask to a bitwise-OR of one or more of the following purge flags:
Purges all read (IRP_MJ_READ) requests.
Purges the receive buffer, if one exists.
Purges all write (IRP_MJ_WRITE) requests.
Purges the transmit buffer, if one exists.
The Parameters.DeviceIoControl.InputBufferLength member is set to the size, in bytes, of a ULONG.
If the request is successful, the Information member is set to the size, in bytes, of a ULONG. Otherwise, the Information member is set to zero.
The Status member is set to one of the Generic Status Values for Serial Device Control Requests. A status of STATUS_INVALID_PARAMETER indicates that the purge mask is not valid.
Serial.sys and SerCx allow an IOCTL_SERIAL_PURGE request to specify any combination of one or more SERIAL_PURGE_XXX flags. However, SerCx2 is more restrictive.
SerCx2 requires that all read requests be purged if the receive buffer is purged. Thus, if the SERIAL_PURGE_RXCLEAR flag is set in an IOCTL_SERIAL_PURGE request, then either the SerCx2 I/O request queue must not contain any read requests, or the SERIAL_PURGE_RXABORT flag must be set. Otherwise, the IOCTL_SERIAL_PURGE request fails with a STATUS_INVALID_DEVICE_STATE status code.
Similarly, SerCx2 requires that all write requests be purged if the transmit buffer is purged. Thus, if the SERIAL_PURGE_TXCLEAR flag is set in an IOCTL_SERIAL_PURGE request, then either the SerCx2 I/O request queue must must not contain any write requests, or the SERIAL_PURGE_TXABORT flag must be set. Otherwise, the IOCTL_SERIAL_PURGE request fails with a STATUS_INVALID_DEVICE_STATE status code.
For more information about SerCx2, SerCx, and Serial.sys, see Serial Controller Drivers Overview.