The following summarizes the I/O control codes handled by serial drivers.
IOCTL_SERIAL_GET_STATS
Operation
Returns the current values of the performance statistics for the device. The statistics include the number of characters transmitted, the number of characters received, and various errors. The values increase until they are explicitly reset with SERIAL_IOCTL_CLEAR_STATS.
If a driver does not implement this IOCTL, it should return an error and not modify the output buffer. If the modem driver is involved in processing the I/O, it will adjust the return value from error to success but only return zeros for the counter values.
Input
Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIALPERF_STATS).
Output
The driver returns data to the buffer at Irp->AssociatedIrp.SystemBuffer.
I/O Status Block
The Information field is set to sizeof(SERIALPERF_STATS) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero if the Status field is set to STATUS_BUFFER_TOO_SMALL.
IOCTL_SERIAL_CLEAR_STATS
Operation
Resets the performance statistics for the device.
Input
None.
Output
None
I/O Status Block
The Information field is set to zero and the Status field is set to STATUS_SUCCESS.
IOCTL_SERIAL_GET_PROPERTIES
Operation
Returns information about the characteristics of the attached communication device.
Input
Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_COMMPROP).
Output
The driver returns the information to the buffer at
Irp->AssociatedIrp.SystemBuffer.
I/O Status Block
The Information field is set to sizeof(SERIAL_COMMPROP) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero and the Status field is set to STATUS_BUFFER_TOO_SMALL.
IOCTL_SERIAL_GET_MODEMSTATUS
Operation
Returns a bitmask indicating the status.
Input
Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(ULONG).
Output
The driver returns the bitmask to the buffer at
Irp->AssociatedIrp.SystemBuffer.
I/O Status Block
The Information field is set to sizeof(ULONG) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero and the Status field is set to STATUS_BUFFER_TOO_SMALL.
IOCTL_SERIAL_GET_COMMSTATUS
Operation
Returns general status information, including how many Errors and HoldReasons have occurred, how much data is in the driver’s buffers as indicated by the AmountInInQueue and AmountInOutQueue values, and whether EofReceived and WaitForImmediate are set.
Input
Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_STATUS).
Output
The driver returns information to the buffer at
Irp->AssociatedIrp.SystemBuffer.
I/O Status Block
The Information field is set to sizeof(SERIAL_STATUS) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero and the Status field is set to STATUS_BUFFER_TOO_SMALL.
IOCTL_SERIAL_RESET_DEVICE
Operation
Sets the device to a known state.
Input
None
Output
None
I/O Status Block
The Status field is set to STATUS_SUCCESS and the Information field is set to zero.
IOCTL_SERIAL_PURGE
Operation
Purges the specified operation(s) or queues: one or more of the current and all pending writes, the current and all pending reads, the transmit buffer if one exists, and the receive buffer if one exists.
Input
Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer at Irp->AssociatedIrp.SystemBuffer, which contains a bitmask of type ULONG, indicating what to purge.
Output
None
I/O Status Block
The Information field is set to zero, and the Status field is set to STATUS_SUCCESS or possibly to STATUS_PENDING, STATUS_CANCELLED, or STATUS_INVALID_PARAMETER.
IOCTL_SERIAL_LSRMST_INSERT
Operation
Enables or disables insertion of the line status or modem status into the RX stream at the behest of a user-mode application.While this state is enabled, the serial driver inserts the caller-supplied escape character, together with one of the following, into the data stream being read from the device:
·SERIAL_LSRMST_LSR_DATA, indicating that a line-status change occurred. Immediately following this, the driver inserts the value of the line status register and the character present in the receive hardware when the line-status change was processed.
·SERIAL_LSRMST_LSR_NODATA, indicating that a line-status change occurred but that no data was available in the receive buffer. Immediately following this, the driver inserts the value of the line status register when the line-status change was processed.
·SERIAL_LSRMST_MST, indicating that a modem-status change occurred. Immediately following this, the driver inserts the value of the modem status register when the modem-status change was processed.
·SERIAL_LSRMST_ESCAPE, indicating that the next character in the stream, which was received from the device, is identical to the caller-supplied escape character.
Input
Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer at Irp->AssociatedIrp.SystemBuffer, which contains a value of type UCHAR, indicating whether to enable LSRMST-insertion mode. A value of zero indicates the driver should disable LSRMST-insertion mode. A nonzero value is the caller-supplied escape character.
Output
None
I/O Status Block
The Information field is set to zero. The Status field is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_INVALID_PARAMETER if the input escape character is the same as the current XOFF or XON character, or if handflow error replacement is enabled.
IOCTL_SERIAL_GET_BAUD_RATE
Operation
Returns the current baud-rate setting.
Input
Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_BAUD_RATE).
Output
The driver returns the data to the buffer at Irp->AssociatedIrp.SystemBuffer.
I/O Status Block
The Information field is set to sizeof(SERIAL_BAUD_RATE) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero, and the Status field is set to STATUS_BUFFER_TOO_SMALL.
IOCTL_SERIAL_SET_BAUD_RATE
Operation
Sets the speed at which characters are sent over the serial line.
Input
Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_BAUD_RATE)) of the buffer at
Irp->AssociatedIrp.SystemBuffer.
Output
None
I/O Status Block
The Information field is set to zero. The Status field is set to STATUS_SUCCESS or possibly to STATUS_INVALID_PARAMETER or STATUS_BUFFER_TOO_SMALL.
IOCTL_SERIAL_SET_QUEUE_SIZE
Operation
Resizes the driver’s internal typeahead and input buffers. The driver can allocate buffers larger than the requested sizes and can refuse to allocate buffers larger than its capacity.
Input
Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_QUEUE_SIZE)) of the buffer at Irp->AssociatedIrp.SystemBuffer, containing the InSize and OutSize specifications.
Output
None
I/O Status Block
The Information field is set to zero. The Status field is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_INSUFFICIENT_RESOURCES if the driver cannot satisfy the request by allocating more memory.
IOCTL_SERIAL_GET_HANDFLOW
Operation
Returns the current values for the flow control and handshaking.
Input
Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_HANDFLOW).
Output
The driver returns the information to the buffer at Irp->AssociatedIrp.SystemBuffer.
I/O Status Block
The Information field is set to sizeof(SERIAL_HANDFLOW) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero and the Status field is set to STATUS_BUFFER_TOO_SMALL.
IOCTL_SERIAL_SET_HANDFLOW
Operation
Sets up flow control and handshaking for subsequent operations.
Input
Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_HANDFLOW)) of the buffer at Irp->AssociatedIrp.SystemBuffer, which contains the values to be set.
Output
None
I/O Status Block
The Information field is set to zero, and the Status field can be set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_INVALID_PARAMETER.
IOCTL_SERIAL_GET_LINE_CONTROL
Operation
Returns the current values of the stop-bits, parity, and word-length parameters for the device.
Input
Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_LINE_CONTROL).
Output
The driver returns data to the buffer at Irp->AssociatedIrp.SystemBuffer.
I/O Status Block
The Information field is set to sizeof(SERIAL_LINE_CONTROL) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero if the Status field is set to STATUS_BUFFER_TOO_SMALL.
IOCTL_SERIAL_SET_LINE_CONTROL
Operation
Resets the stop-bits, parity, and word-length parameters for the device.
Input
Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_LINE_CONTROL)) of the buffer at Irp->AssociatedIrp.SystemBuffer.
Output
None
I/O Status Block
The Information field is set to zero. The Status field is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_INVALID_PARAMETER.
IOCTL_SERIAL_SET_BREAK_ON
Operation
Causes a break condition to be transmitted by the UART.
Input
None
Output
None
I/O Status Block
The Status field is set to STATUS_SUCCESS and the Information field is set to zero.
IOCTL_SERIAL_SET_BREAK_OFF
Operation
Disables the transmission of break conditions by the UART.
Input
None
Output
None
I/O Status Block
The Status field is set to STATUS_SUCCESS and the Information field is set to zero.
IOCTL_SERIAL_GET_TIMEOUTS
Operation
Returns the current settings for read and write time-outs on the device.
Input
Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_TIMEOUTS).
Output
The driver returns information to the buffer at Irp->AssociatedIrp.SystemBuffer.
I/O Status Block
The Information field is set to sizeof(SERIAL_TIMEOUTS) when the Status field is set to STATUS_SUCCESS. The Information field is set to zero when the Status field is set to STATUS_BUFFER_TOO_SMALL.
IOCTL_SERIAL_SET_TIMEOUTS
Operation
Sets up time-out constraints for serial I/O operations.
Input
Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_TIMEOUTS)) of the buffer at Irp->AssociatedIrp.SystemBuffer.
Output
None
I/O Status Block
The Information field is set to zero. The Status field can be set to STATUS_SUCCESS or STATUS_BUFFER_TOO_SMALL.
IOCTL_SERIAL_IMMEDIATE_CHAR
Operation
Causes a single character to be transmitted as soon as the hardware is available.
Input
The buffer at Irp->AssociatedIrp.SystemBuffer contains the character to be sent. Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(UCHAR).
Output
None
I/O Status Block
The Information field is set to one when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero, and the Status field can be set to STATUS_PENDING, STATUS_CANCELLED, STATUS_BUFFER_TOO_SMALL, or STATUS_INVALID_PARAMETER if another immediate character is already pending.
IOCTL_SERIAL_XOFF_COUNTER
Operation
Sends the specified XOFF character, sets up a timer to track the specified time-out value, and decrements the supplied count of characters for each subsequently written character until the count goes to zero or a time-out occurs. This IOCTL supports software emulation of the serial chip in certain protected subsystems.
Input
Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_XOFF_COUNTER)) of the buffer at Irp->AssociatedIrp.SystemBuffer, which contains the data.
Output
None
I/O Status Block
The Information field is set to zero. The Status field can be set to STATUS_SUCCESS (all requested characters written) or possibly to STATUS_SERIAL_MORE_WRITES, STATUS_SERIAL_COUNTER_TIMEOUT, STATUS_BUFFER_TOO_SMALL, or STATUS_INVALID_PARAMETER if the XoffChar specified is inconsistent with the current flow-control specification.
IOCTL_SERIAL_SET_DTR
Operation
Sets DTR (data terminal ready).
Input
None
Output
None
I/O Status Block
The Information field is set to zero. The Status field can be set to STATUS_SUCCESS or to STATUS_INVALID_PARAMETER if the current handshake setup is inconsistent with the requested operation.
IOCTL_SERIAL_CLR_DTR
Operation
Clears DTR.
Input
None
Output
None
I/O Status Block
The Information field is set to zero. The Status field can be set to STATUS_SUCCESS or to STATUS_INVALID_PARAMETER if the current handshake setup is inconsistent with the requested operation.
IOCTL_SERIAL_SET_RTS
Operation
Sets RTS (request to send).
Input
None
Output
None
I/O Status Block
The Information field is set to zero. The Status field can be set to STATUS_SUCCESS or to STATUS_INVALID_PARAMETER if the current handshake setup is inconsistent with the requested operation.
IOCTL_SERIAL_CLR_RTS
Operation
Clears RTS.
Input
None
Output
None
I/O Status Block
The Information field is set to zero. The Status field can be set to STATUS_SUCCESS or to STATUS_INVALID_PARAMETER if the current handshake setup is inconsistent with the requested operation.
IOCTL_SERIAL_GET_DTRRTS
Operation
Returns the state of the DTR and RTS lines at the time this request is processed.
Input
Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(ULONG).
Output
The driver returns information to the buffer at
Irp->AssociatedIrp.SystemBuffer.
I/O Status Block
The Information field is set to sizeof(ULONG) when the Status field is set to STATUS_SUCCESS. The Information field is set to zero when the Status field is set to STATUS_BUFFER_TOO_SMALL.
IOCTL_SERIAL_SET_XON
Operation
Enables emulation of receipt of characters, which the serial driver might already have in its internal buffers.
Input
None
Output
None
I/O Status Block
The Status field is set to STATUS_SUCCESS and the Information field is set to zero.
IOCTL_SERIAL_SET_XOFF
Operation
Disables emulation of receipt of characters.
Input
None
Output
None
I/O Status Block
The Status field is set to STATUS_SUCCESS and the Information field is set to zero.
IOCTL_SERIAL_GET_WAIT_MASK
Operation
Returns the current value of the event wait mask.
Input
Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(ULONG).
Output
The driver returns the information to the buffer at Irp->AssociatedIrp.SystemBuffer.
I/O Status Block
The Information field is set to sizeof(ULONG) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero, and the Status field can be set to STATUS_PENDING, STATUS_CANCELLED, or STATUS_BUFFER_TOO_SMALL.
IOCTL_SERIAL_SET_WAIT_MASK
Operation
Causes the driver to track the specified events, or, if the specified value is zero, to complete pending waits.
Input
Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(ULONG)) of the bitmask at Irp->AssociatedIrp.SystemBuffer.
Output
None
I/O Status Block
The Information field is set to zero. The Status field is set to STATUS_SUCCESS or possibly to STATUS_PENDING, STATUS_CANCELLED, STATUS_BUFFER_TOO_SMALL, or STATUS_INVALID_PARAMETER.
IOCTL_SERIAL_WAIT_ON_MASK
Operation
Returns information about which events have occurred among those that the caller was waiting on.
Input
Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes (must be >= sizeof(ULONG)) of the buffer.
Output
The driver returns a bitmask with bits set for events that occurred (or with a value of zero if the preceding set-waitmask request specified zero) to the buffer at Irp->AssociatedIrp.SystemBuffer.
I/O Status Block
The Information field is set to sizeof(ULONG) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero, and the Status field can be set to STATUS_PENDING or STATUS_INVALID_PARAMETER if a wait is already pending.
IOCTL_SERIAL_GET_CHARS
Operation
Returns the current values for the special characters used by the driver.
Input
Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(SERIAL_CHARS).
Output
The driver returns the information to the buffer at
Irp->AssociatedIrp.SystemBuffer.
I/O Status Block
The Information field is set to sizeof(SERIAL_CHARS) when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero and the Status field is set to STATUS_BUFFER_TOO_SMALL.
IOCTL_SERIAL_SET_CHARS
Operation
Sets special characters (EofChar, ErrorChar, BreakChar, EventChar, XonChar, and XoffChar) used by the driver.
Input
Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (must be >= sizeof(SERIAL_CHARS)) of the buffer at Irp->AssociatedIrp.SystemBuffer, which contains the values to the used.
Output
None
I/O Status Block
The Information field is set to zero, and the Status field is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_INVALID_PARAMETER if the specified values for XonChar and XoffChar are identical.