EVT_SERCX_PURGE callback function

Description

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

Parameters

Device [in]

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

PurgeMask [in]

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.

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.

See also

EvtDriverDeviceAdd

IOCTL_SERIAL_PURGE

SerCxInitialize