UID

title

description

old-location

tech.root

ms.date

keywords

ms.keywords

req.header

req.include-header

req.target-type

req.target-min-winverclnt

req.target-min-winversvr

req.kmdf-ver

req.umdf-ver

req.ddi-compliance

req.unicode-ansi

req.idl

req.max-support

req.namespace

req.assembly

req.type-library

req.lib

req.dll

req.irql

targetos

req.typenames

f1_keywords

topic_type

api_type

api_location

api_name

NC:sercx.EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO

EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO (sercx.h)

The EvtSerCx2PioTransmitPurgeFifo event callback function is called by version 2 of the serial framework extension (SerCx2) to discard any bytes of unsent data that remain in the transmit FIFO in the serial controller.

serports\evtsercx2piotransmitpurgefifo.htm

serports

04/23/2018

EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO callback function

2/EvtSerCx2PioTransmitPurgeFifo, EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO, EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO callback, EvtSerCx2PioTransmitPurgeFifo, EvtSerCx2PioTransmitPurgeFifo callback function [Serial Ports], serports.evtsercx2piotransmitpurgefifo

sercx.h

Desktop

Available starting with Windows 8.1.

Called at IRQL <= DISPATCH_LEVEL.

Windows

EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO

sercx/EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO

APIRef

kbSyntax

UserDefined

2.0\Sercx.h

EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO

EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO callback function

-description

The EvtSerCx2PioTransmitPurgeFifo event callback function is called by version 2 of the serial framework extension (SerCx2) to discard any bytes of unsent data that remain in the transmit FIFO in the serial controller.

-parameters

-param PioTransmit [in]

A SERCX2PIOTRANSMIT handle to a PIO-transmit object. The serial controller driver previously called the SerCx2PioTransmitCreate method to create this object.

-param BytesAlreadyTransmittedToHardware [in]

The number of bytes that have already been loaded into the transmit FIFO during the current PIO-transmit transaction. This parameter is the sum of all the bytes transferred in previous calls to the EvtSerCx2PioTransmitWriteBuffer event callback function that are part of this transaction.

-remarks

Your serial controller driver can, as an option, implement this function. If implemented, the driver registers the function in the SerCx2PioTransmitCreate call that creates the PIO-transmit object.

Your driver should implement an EvtSerCx2PioTransmitPurgeFifo function if the serial controller has a hardware FIFO (or similar buffering mechanism) to hold transmit data. If your driver implements this function, it must also implement the EvtSerCx2PioTransmitDrainFifo and EvtSerCx2PioTransmitCancelDrainFifo event callback functions.

SerCx2 initiates a PIO-transmit transaction in response to a write (IRP_MJ_WRITE) request from a client. If this request times out or is canceled before it completes, SerCx2 calls the EvtSerCx2PioTransmitPurgeFifo function, if it is implemented, to purge any unsent data that might remain the transmit FIFO.

After the transmit FIFO is purged, the EvtSerCx2PioTransmitPurgeFifo function must call the SerCx2PioTransmitPurgeFifoComplete method to notify SerCx2 that the FIFO was purged, and SerCx2 then completes the write request.

For more information, see SerCx2 PIO-Transmit Transactions.

Examples

To define an EvtSerCx2PioTransmitPurgeFifo 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 EvtSerCx2PioTransmitPurgeFifo callback function that is named MyPioTransmitPurgeFifo, use the EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO function type, as shown in this code example:

EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO  MyPioTransmitPurgeFifo;

Then, implement your callback function as follows:

_Use_decl_annotations_
VOID
  MyPioTransmitPurgeFifo(
    SERCX2PIOTRANSMIT  PioTransmit,
    ULONG  BytesAlreadyTransmittedToHardware

    )
  {...}

The EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO 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_PIO_TRANSMIT_PURGE_FIFO 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.