EVT_SERCX_CONTROL callback function (sercx.h)

Article
10/21/2021

The EvtSerCxControl event callback function handles an I/O control request that has an I/O control code (IOCTL) that the serial framework extension (SerCx) supports.

Syntax

EVT_SERCX_CONTROL EvtSercxControl;

NTSTATUS EvtSercxControl(
  [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.

[in] Request

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

[in] OutputBufferLength

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

[in] InputBufferLength

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

[in] IoControlCode

Specifies the IOCTL from the I/O control request specified by the Request parameter.

Return value

The EvtSerCxControl function returns STATUS_SUCCESS if the call is successful. Otherwise, it returns an appropriate error status code. For more information, see the following Remarks section.

Remarks

The serial controller driver is required to implement this callback function. SerCx calls this function to hand off an I/O control request to the controller driver for processing. Before this function returns, it must complete the request either by performing the requested operation or by returning an error status. A driver that does not implement support for a particular request should return the STATUS_NOT_IMPLEMENTED error status for this request.

Typically, the EvtSerCxControl function should synchronize to the controller driver's ISR before this function changes the settings in the hardware registers of the serial controller.

The EvtSerCxControl function's return value must match the status value that this function writes to the status block of the I/O control request. SerCx uses the return value to track the state of the controller driver and the serial controller hardware.

The following is a list of the IOCTLs that this callback function must be prepared to handle:

IOCTL_SERIAL_CLEAR_STATS IOCTL_SERIAL_CLR_DTR IOCTL_SERIAL_CLR_RTS IOCTL_SERIAL_GET_BAUD_RATE IOCTL_SERIAL_GET_CHARS IOCTL_SERIAL_GET_COMMSTATUS IOCTL_SERIAL_GET_DTRRTS IOCTL_SERIAL_GET_HANDFLOW IOCTL_SERIAL_IMMEDIATE_CHAR IOCTL_SERIAL_GET_LINE_CONTROL IOCTL_SERIAL_GET_MODEM_CONTROL IOCTL_SERIAL_GET_MODEMSTATUS IOCTL_SERIAL_GET_PROPERTIES IOCTL_SERIAL_GET_STATS IOCTL_SERIAL_LSRMST_INSERT IOCTL_SERIAL_SET_BAUD_RATE IOCTL_SERIAL_SET_BREAK_OFF IOCTL_SERIAL_SET_BREAK_ON IOCTL_SERIAL_SET_CHARS IOCTL_SERIAL_SET_DTR IOCTL_SERIAL_SET_FIFO_CONTROL IOCTL_SERIAL_SET_HANDFLOW IOCTL_SERIAL_SET_LINE_CONTROL IOCTL_SERIAL_SET_MODEM_CONTROL IOCTL_SERIAL_SET_RTS IOCTL_SERIAL_SET_XOFF IOCTL_SERIAL_SET_XON IOCTL_SERIAL_XOFF_COUNTER To register an EvtSerCxControl callback function, the controller driver calls the SerCxInitialize method during the EvtDriverDeviceAdd callback.

Examples

The function type for this callback is declared in Sercx.h, as follows.

typedef NTSTATUS
  EVT_SERCX_CONTROL(
    __in WDFREQUEST Request,
    __in size_t OutputBufferLength,
    __in size_t InputBufferLength,
    __in ULONG IoControlCode
    );

To define an EvtSerCxControl callback function that is named MyEvtSerCxControl, you must first provide a function declaration that Static Driver Verifier (SDV) and other verification tools require, as follows.

EVT_SERCX_CONTROL MyEvtSerCxControl;

Then, implement your callback function as follows.

NTSTATUS
  MyEvtSerCxControl(
    __in WDFREQUEST Request,
    __in size_t OutputBufferLength,
    __in size_t InputBufferLength,
    __in ULONG IoControlCode
    )
{ ... }

For more information about SDV requirements for function declarations, see Declaring Functions Using Function Role Types for KMDF Drivers.

Requirements

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

Share via