EVT_SERCX_PURGE callback function (sercx.h)

Article
10/21/2021

The EvtSerCxPurge event callback function is called by the serial framework extension (SerCx) to purge the serial controller's hardware buffers.

Syntax

EVT_SERCX_PURGE EvtSercxPurge;

NTSTATUS EvtSercxPurge(
  [in] WDFDEVICE Device,
  [in] ULONG PurgeMask
)
{...}

Parameters

[in] Device

A WDFDEVICE handle to the framework device object that represents the serial controller.

[in] PurgeMask

A set of flags that describe the hardware buffers that are to be purged. Currently, no flags are defined for purge operations that are performed by the serial controller. For more information, see Remarks.

Return value

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

Remarks

The serial controller driver implements this callback function. SerCx calls this function when a client (application or peripheral driver) sends an IOCTL_SERIAL_PURGE control request that requires hardware buffers managed by the serial controller to be purged.

SerCx performs the purge operations that are designated by the flags listed in the following table.

Flag bit	Meaning
SERIAL_PURGE_RXABORT	Purge all read requests.
SERIAL_PURGE_RXCLEAR	Purge the input buffer, if one exists. Any receive data in this buffer is discarded.
SERIAL_PURGE_TXABORT	Purge all write requests.
SERIAL_PURGE_TXCLEAR	Purge the output buffer, if one exists. Any transmit data in this buffer is discarded.

The EvtSerCxPurge function will never receive a purge request that contains any of the flags in this table. The SERIAL_PURGE_XXX flags are defined in the Ntddser.h header file.

Currently, no SERIAL_PURGE_XXX flags are defined to designate purge operations that are performed by the serial controller driver, and the serial controller driver should perform no purge operations in response to a EvtSerCxPurge call.

If the IOCTL_SERIAL_PURGE control request requires pending read or write requests to be canceled, SerCx cancels these requests before it calls the EvtSerCxPurge function.

To register an EvtSerCxPurge 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_PURGE(
    __in WDFDEVICE Device,
    __in ULONG PurgeMask
    );

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

EVT_SERCX_PURGE MyEvtSerCxPurge;

Then, implement your callback function as follows.

NTSTATUS
  MyEvtSerCxPurge(
    __in WDFDEVICE Device,
    __in ULONG PurgeMask
    )
{ ... }

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