IOCTL_SERIAL_SET_WAIT_MASK control code

The IOCTL_SERIAL_SET_WAIT_MASK request configures the serial controller driver to notify a client after the occurrence of any one of a specified set of wait events.

A client can wait for the wait events represented by flag bits SERIAL_EV_RXCHAR through SERIAL_EV_EVENT2. For more information about these event flags, see the Remarks section.

A client specifies wait events by setting an input event wait mask to the bitwise-OR of one or more of the event flags. A client can clear all wait events by setting the input event wait mask to zero.

A client uses an IOCTL_SERIAL_WAIT_ON_MASK request to wait for the occurrence of a wait event. If a wait-on-mask request is already pending when a set-wait-mask request is processed, the pending wait-on-event request is completed with a status of STATUS_SUCCESS and the output wait event mask is set to zero.

Input Parameters

The AssociatedIrp.SystemBuffer member points to a ULONG buffer that the client allocates and sets to an event wait mask. The wait mask is set to zero or to the bitwise-OR of one or more SERIAL_EV_XXX flags bits.

The Parameters.DeviceIoControl.InputBufferLength member is set to the size, in bytes, of a ULONG.

Output Parameters

None.

I/O Status Block

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 input wait mask is not valid.

Remarks

The SERIAL_EV_XXX constants define the flag bits in the wait mask for a serial port.


#define SERIAL_EV_RXCHAR     0x0001
#define SERIAL_EV_RXFLAG     0x0002
#define SERIAL_EV_TXEMPTY    0x0004
#define SERIAL_EV_CTS        0x0008
#define SERIAL_EV_DSR        0x0010
#define SERIAL_EV_RLSD       0x0020
#define SERIAL_EV_BREAK      0x0040
#define SERIAL_EV_ERR        0x0080
#define SERIAL_EV_RING       0x0100
#define SERIAL_EV_PERR       0x0200
#define SERIAL_EV_RX80FULL   0x0400
#define SERIAL_EV_EVENT1     0x0800
#define SERIAL_EV_EVENT2     0x1000

SERIAL_EV_RXCHAR

A character was received and placed in the input buffer.

SERIAL_EV_RXFLAG

The event character was received and placed in the input buffer. The event character value is set by the IOCTL_SERIAL_SET_CHARS request.

SERIAL_EV_TXEMPTY

The last character was transmitted from the output buffer, which is now empty.

SERIAL_EV_CTS

The CTS (clear to send) signal changed state.

SERIAL_EV_DSR

The DSR (data set ready) signal changed state.

SERIAL_EV_RLSD

The RLSD (receive line signal detect) signal changed state.

SERIAL_EV_BREAK

A break was detected in the input stream.

SERIAL_EV_ERR

A line status error occurred. Possible line status errors are SERIAL_ERROR_FRAMING, SERIAL_ERROR_OVERRUN, and SERIAL_ERROR_PARITY. For more information about these errors, see the description of the Errors member in SERIAL_STATUS.

SERIAL_EV_RING

A ring signal was detected.

SERIAL_EV_PERR

A printer error occurred.

SERIAL_EV_RX80FULL

The receive buffer is 80 percent full.

SERIAL_EV_EVENT1

Provider-specific event number 1 occurred.

SERIAL_EV_EVENT2

Provider-specific event number 2 occurred.

The SERIAL_EV_XXX constants define the types of events that can be specified in a wait mask. After a client (application or peripheral driver) opens a connection to a serial port, the client can specify a wait mask that indicates the types of events that the client needs to monitor. These events are changes in the hardware state of the serial port. When an event in the wait mask occurs, the client is notified.

The IOCTL_SERIAL_SET_WAIT_MASK and IOCTL_SERIAL_GET_WAIT_MASK control requests use event wait masks to specify a set of events on which a client can wait. A wait mask value is either zero or the bitwise-OR of one or more SERIAL_EV_XXX constants. A wait mask value of zero indicates that the client is not waiting for any events.

The client sends an IOCTL_SERIAL_WAIT_ON_MASK control request to wait for an event in the currently set wait mask. The serial controller driver completes this request when an event in the wait mask occurs.

The following table shows which SERIAL_EV_XXX flag bits are supported by SerCx2, SerCx, and Serial.sys. A Yes entry in the table indicates that the serial framework extension or driver supports the corresponding flag bit. A No entry indicates that the flag bit is not supported.

Flag bitSerCx2SerCxSerial.sys
SERIAL_EV_RXCHARYesYesYes
SERIAL_EV_RXFLAGSee note.NoYes
SERIAL_EV_TXEMPTYYesYesYes
SERIAL_EV_CTSYesYesYes
SERIAL_EV_DSRYesYesYes
SERIAL_EV_RLSDSee note.YesYes
SERIAL_EV_BREAKYesYesYes
SERIAL_EV_ERRYesYesYes
SERIAL_EV_RINGSee note.YesYes
SERIAL_EV_PERRSee note.NoNo
SERIAL_EV_RX80FULLSee note.NoYes
SERIAL_EV_EVENT1See note.NoNo
SERIAL_EV_EVENT2See note.NoNo

 

Note  SerCx2 may or may not support the flag bit in the indicated table entry, depending on the serial controller driver and the capabilities of the serial controller hardware.
 

For more information about SerCx2, SerCx, and Serial.sys, see Serial Controller Drivers Overview.

Requirements

Header

Ntddser.h (include Ntddser.h)

See also

IOCTL_SERIAL_GET_CHARS
IOCTL_SERIAL_GET_WAIT_MASK
IOCTL_SERIAL_SET_CHARS
IOCTL_SERIAL_WAIT_ON_MASK
SERIAL_CHARS
SERIAL_STATUS

 

 

Send comments about this topic to Microsoft

Show: