EVT_SERCX2_CONTROL callback function (sercx.h)

Article
10/21/2021

The EvtSerCx2Control event callback function is called by version 2 of the serial framework extension (SerCx2) to handle a serial I/O control request.

Syntax

EVT_SERCX2_CONTROL EvtSercx2Control;

NTSTATUS EvtSercx2Control(
  [in] WDFDEVICE Device,
  [in] WDFREQUEST Request,
  [in] size_t OutputBufferLength,
  [in] size_t InputBufferLength,
  [in] ULONG IoControlCode
)
{...}

Parameters

[in] Device

A WDFDEVICE handle to the framework device object that represents the serial controller. The serial controller driver created this object in its EvtDriverDeviceAdd callback function. For more information, see SerCx2InitializeDevice.

[in] Request

A WDFREQUEST handle to the framework request object that represents the serial I/O control request.

[in] OutputBufferLength

The length, in bytes, of the output buffer for the serial I/O control request specified by the Request parameter.

[in] InputBufferLength

The length, in bytes, of the input buffer for the serial I/O control request specified by the Request parameter.

[in] IoControlCode

Specifies the I/O control code (IOCTL) from the serial I/O control request specified by the Request parameter. The IOCTLs for serial I/O control requests are defined in the Ntddser.h header file. For more information, see Remarks.

Return value

The EvtSerCx2Control function returns STATUS_SUCCESS if the call is successful. Otherwise, it returns an appropriate error status code.

Remarks

Your serial controller driver must implement this function. The driver registers the function in the call to the SerCx2InitializeDevice method that finishes the initialization of the framework device object for the serial controller.

The EvtSerCx2Control function lets your driver handle certain serial I/O control requests that SerCx2 cannot handle. SerCx2 handles all processing for a subset of the serial IOCTLs that are defined in the Ntddser.h header file. However, SerCx2 relies on the driver to handle serial I/O control requests to perform hardware-dependent operations.

When SerCx2 receives a serial I/O control request that can be handled only by the serial controller driver, SerCx2 calls the EvtSerCx2Control function to hand off the I/O control request to the driver. The driver is responsible for completing this request. A driver that does not implement support for a particular I/O control request should complete this I/O control request with the STATUS_NOT_SUPPORTED error status code.

To complete the I/O control request, the driver typically calls the WdfRequestComplete method and supplies, as input parameters, the Request parameter value and a status value to indicate whether the request was successful. This status value is written to the status block of the request.

The EvtSerCx2Control function's return value should always match the status value that this function writes to the status block of the I/O control request. The current implementation of SerCx2 ignores this return value.

SerCx2 calls the EvtSerCx2Control function to handle the IOCTLs shown in the following table. The column on the right side of the table indicates whether the EvtSerCx2Control function is required to implement support for a particular IOCTL.

I/O control request name	Required or optional
IOCTL_SERIAL_CLR_DTR	Optional
IOCTL_SERIAL_CLR_RTS	Required
IOCTL_SERIAL_GET_BAUD_RATE	Required
IOCTL_SERIAL_GET_COMMSTATUS	Required
IOCTL_SERIAL_GET_DTRRTS	Required
IOCTL_SERIAL_GET_HANDFLOW	Required
IOCTL_SERIAL_GET_LINE_CONTROL	Required
IOCTL_SERIAL_GET_MODEM_CONTROL	Required
IOCTL_SERIAL_GET_MODEMSTATUS	Required
IOCTL_SERIAL_GET_PROPERTIES	Required
IOCTL_SERIAL_SET_BAUD_RATE	Required
IOCTL_SERIAL_SET_BREAK_OFF	Required
IOCTL_SERIAL_SET_BREAK_ON	Required
IOCTL_SERIAL_SET_DTR	Optional
IOCTL_SERIAL_SET_FIFO_CONTROL	Optional
IOCTL_SERIAL_SET_HANDFLOW	Required
IOCTL_SERIAL_SET_LINE_CONTROL	Required
IOCTL_SERIAL_SET_MODEM_CONTROL	Required
IOCTL_SERIAL_SET_RTS	Required

The preceding table lists all of the serial IOCTLs that SerCx2 presents to the EvtSerCx2Control function. For any IOCTL not in this list, SerCx2 either handles the IOCTL, or immediately fails the IOCTL and sets the request status to STATUS_NOT_SUPPORTED. SerCx2 handles IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION requests, but calls the EvtSerCx2ApplyConfig event callback function during the processing of such a request. SerCx2 handles IOCTL_SERIAL_PURGE requests, but might call the EvtSerCx2PurgeFifos event callback function during the processing of such a request. SerCx does preliminary processing of IOCTL_SERIAL_SET_WAIT_MASK requests, but calls the EvtSerCx2SetWaitMask event callback function, if it is implemented, to finish handling such a request. For more information about SerCx2 support for serial IOCTLs, see Serial I/O Request Interface.

IOCTL_SERIAL_CLR_DTR and IOCTL_SERIAL_SET_DTR

If the EvtSerCx2Control function in your serial controller driver supports the IOCTL_SERIAL_SET_DTR request, this function should also support the IOCTL_SERIAL_CLR_DTR request, and vice versa. If your driver does not support these two requests, the driver's handler for the IOCTL_SERIAL_GET_DTRRTS request should set the SERIAL_DTR_STATE flag bit in the output value for this request to zero.

IOCTL_SERIAL_GET_DTRRTS

The EvtSerCx2Control function in your serial controller driver must support the IOCTL_SERIAL_GET_DTRRTS request, but the driver's handler for this request is required to support only the SERIAL_RTS_STATE flag bit in the output value for this request. As an option, the driver can additionally support the SERIAL_DTR_STATE flag bit. If the SERIAL_DTR_STATE flag bit is not supported, set this bit to zero.

IOCTL_SERIAL_GET_COMMSTATUS

The EvtSerCx2Control function in your serial controller driver must support the IOCTL_SERIAL_GET_COMMSTATUS request, but the driver's handler for this request is required to support only the following members of the SERIAL_STATUS structure used by this request:

Errors
HoldReasons

As an option, the driver can additionally support any of the other members of this structure. Set all unsupported members to zero.

IOCTL_SERIAL_GET_PROPERTIES

The EvtSerCx2Control function in your serial controller driver must support the IOCTL_SERIAL_GET_PROPERTIES request. The driver's handler for this request should set the MaxBaud member of the SERIAL_COMMPROP structure used by this request to the maximum supported baud rate, expressed in bits per second (bps). For example, if the serial controller supports a maximum baud rate of 115,200 bps, the driver sets MaxBaud = 115200.

IOCTL_SERIAL_GET_MODEMSTATUS

The EvtSerCx2Control function in your serial controller driver must support the IOCTL_SERIAL_GET_MODEMSTATUS request. The driver's handler for this request should set the request's output value to the raw modem status register value read from the serial controller hardware.

IOCTL_SERIAL_GET_HANDFLOW and IOCTL_SERIAL_SET_HANDFLOW

The EvtSerCx2Control function in your serial controller driver must support the IOCTL_SERIAL_GET_HANDFLOW and IOCTL_SERIAL_SET_HANDFLOW requests, but is required to support only a subset of the flag bits that are defined for these requests. Flag bits are defined for the ControlHandShake and FlowReplace members of the SERIAL_HANDFLOW structure that is used by these requests.

Your driver must support the following flag bit in the ControlHandshake member:

SERIAL_CTS_HANDSHAKE

As an option, a driver can support any of the other flag bits that are defined for the ControlHandshake member.

Your driver must support the following flag bits in the FlowReplace member:

SERIAL_RTS_CONTROL
SERIAL_RTS_HANDSHAKE

As an option, a driver can support any of the other flag bits that are defined for the FlowReplace member. However, these other flag bits are rarely, if ever, needed, and Microsoft recommends against supporting them.

A driver that does not support a particular flag bit in the ControlHandShake or FlowReplace member should set this flag bit to zero in the output value for the IOCTL_SERIAL_GET_HANDFLOW request. If an IOCTL_SERIAL_SET_HANDFLOW request specifies a ControlHandshake or FlowReplace flag bit that the driver does not support, the EvtSerCx2Control function should fail the request and return STATUS_INVALID_PARAMETER.

As an option, a driver can support the XonLimit and XoffLimit members of the SERIAL_HANDFLOW structure. However, these members are rarely, if ever, needed, and Microsoft recommends against supporting them. A driver that does not support the XonLimit and XoffLimit members should set these members to zero in the output value for the IOCTL_SERIAL_GET_HANDFLOW request. If an IOCTL_SERIAL_SET_HANDFLOW request specifies a nonzero XonLimit or XoffLimit member and the driver does not support these members, the EvtSerCx2Control function should fail the request and return STATUS_NOT_IMPLEMENTED.

Examples

To define an EvtSerCx2Control callback function, you must first provide a function declaration that identifies the type of callback function you're defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define an EvtSerCx2Control callback function that is named MyControl, use the EVT_SERCX2_CONTROL function type, as shown in this code example:

EVT_SERCX2_CONTROL  MyControl;

Then, implement your callback function as follows:

_Use_decl_annotations_
NTSTATUS
  MyControl(
    WDFDEVICE  Device,
    WDFREQUEST  Request,
    size_t  OutputBufferLength,
    size_t  InputBufferLength,
    ULONG  IoControlCode
    )
  {...}

The EVT_SERCX2_CONTROL function type is defined in the Sercx.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the EVT_SERCX2_CONTROL function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For more information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 8.1.
Target Platform	Desktop
Header	sercx.h
IRQL	Called at IRQL <= DISPATCH_LEVEL.