EVT_SERCX2_PIO_TRANSMIT_CANCEL_READY_NOTIFICATION callback function (sercx.h)

The EvtSerCx2PioTransmitCancelReadyNotification event callback function is called by version 2 of the serial framework extension (SerCx2) to cancel a ready notification that SerCx2 enabled in a previous call to the EvtSerCx2PioTransmitEnableReadyNotification event callback function.

Syntax

EVT_SERCX2_PIO_TRANSMIT_CANCEL_READY_NOTIFICATION EvtSercx2PioTransmitCancelReadyNotification;

BOOLEAN EvtSercx2PioTransmitCancelReadyNotification(
  [in] SERCX2PIOTRANSMIT PioTransmit
)
{...}

Parameters

[in] PioTransmit

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

Return value

The EvtSerCx2PioTransmitCancelReadyNotification function returns TRUE if the ready notification was successfully disabled and the serial controller driver can guarantee that this notification will not cause the SerCx2PioTransmitReady method to be called.

The function returns FALSE if the driver has already called SerCx2PioTransmitReady, or is about to call this method.

Remarks

Your serial controller driver must implement this function. The driver registers the function in the SerCx2PioTransmitCreate call that creates the PIO-transmit object.

If the associated write request times out or is canceled while a ready notification is enabled, SerCx2 calls the EvtSerCx2PioTransmitCancelReadyNotification function to cancel the pending notification. If this call returns FALSE, SerCx2 expects the serial controller driver to call SerCx2PioTransmitReady; only after this call does SerCx2 call the EvtSerCx2PioTransmitCleanupTransaction event callback function, if it is implemented, and complete the request.

To cancel a previously enabled ready notification, the EvtSerCx2PioTransmitCancelReadyNotification function typically disables the interrupt in the serial controller that indicates that the transmit FIFO is ready to accept more data. SerCx2 enabled this interrupt in a previous call to the EvtSerCx2PioTransmitEnableReadyNotification function.

For more information, see SerCx2 PIO-Transmit Transactions.

Examples

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

EVT_SERCX2_PIO_TRANSMIT_CANCEL_READY_NOTIFICATION  MyPioTransmitCancelReadyNotification;

Then, implement your callback function as follows:

_Use_decl_annotations_
BOOLEAN
  MyPioTransmitCancelReadyNotification(
    SERCX2PIOTRANSMIT  PioTransmit
    )
  {...}

The EVT_SERCX2_PIO_TRANSMIT_CANCEL_READY_NOTIFICATION 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_CANCEL_READY_NOTIFICATION 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

See also

EvtSerCx2PioTransmitEnableReadyNotification

SERCX2PIOTRANSMIT

SerCx2PioTransmitCreate

SerCx2PioTransmitReady