IOCTL_SERIAL_LSRMST_INSERT
The IOCTL_SERIAL_LSRMST_INSERT
DeviceIoControl
operation enables or disables the placement of line status and modem status
values into the regular data stream that an application acquires through the ReadFile function.
When this
line-status and modem-status data placement mode is enabled, status values are
preceded in the data stream by an escape character. The user-definable escape
character is set by the IOCTL_SERIAL_LSRMST_INSERT operation. Status
values consist of 1 to 3 BYTEs. See the Remarks section below for status
value details.
dwIoControlCode = IOCTL_SERIAL_LSRMST_INSERT; // operation code
lpInBuffer;
// address of input buffer
nInBufferSize;
// size of input buffer
lpOutBuffer = NULL; // address of output buffer; not
used; must be NULL
nOutBufferSize = 0; // size of output buffer; not
used; must be zero
lpBytesReturned;
// address of actual bytes of output
Parameters
lpInBuffer
Points to a
buffer that contains a single BYTE.
If the BYTE is a nonzero value, it is the desired line-status
and modem-status value escape character. The operation will turn the LSRMST_INSERT
line-status and modem-status data placement mode on.
If the BYTE is zero, the operation will turn the LSRMST_INSERT
line-status and modem-status data placement mode off.
The escape character can not be the XON or XOFF character.
nInBufferSize
Specifies the
size, in bytes, of the buffer pointed to by lpInBuffer. For this
operation, this value should be 1.
lpOutBuffer
Points to an
output buffer. Not used with this operation. Set to NULL.
nOutBufferSize
Specifies the
size, in bytes, of the buffer pointed to by lpOutBuffer. Not used with
this operation. Set to zero.
lpBytesReturned
Points to a DWORD
that receives the actual size, in bytes, of the data stored into lpOutBuffer.
Return Values
If the
operation succeeds, DeviceIoControl returns TRUE.
If the
operation fails, DeviceIoControl returns FALSE. To get extended error
information, call GetLastError.
Remarks
Note that an
application that uses this scheme must examine each character in the data
stream to determine the presence of modem-status or line-status data.
The following
values follow the designated escape character in the data stream if the LSRMST_INSERT
mode has been turned on :
|
Value |
Meaning |
|
SERIAL_LSRMST_ESCAPE |
Indicates
the reception of the escape character itself into the data stream. |
|
SERIAL_LSRMST_LSR_DATA |
Indicates
that a line status change occurred, and data was available in the receive
hardware buffer. Following this BYTE is a BYTE value of the
line status register is the BYTE present in the receive hardware buffer
when the line status change was processed. |
|
SERIAL_LSRMST_LSR_NODATA |
Indicates
that a line status change occurred, but no data was available in the receive
hardware buffer. |
|
SERIAL_LSRMST_MST |
Indicates
that a modem status change occurred. Following this BYTE is a BYTE
that is the value of the modem status register when the modem status change
was processed. |
See Also