EVT_SERCX2_SYSTEM_DMA_RECEIVE_CANCEL_NEW_DATA_NOTIFICATION callback function (sercx.h)

Article
10/21/2021

The EvtSerCx2SystemDmaReceiveCancelNewDataNotification event callback function is called by version 2 of the serial framework extension (SerCx2) to cancel a new-data notification that SerCx2 enabled in a previous call to the EvtSerCx2SystemDmaReceiveEnableNewDataNotification event callback function.

Syntax

EVT_SERCX2_SYSTEM_DMA_RECEIVE_CANCEL_NEW_DATA_NOTIFICATION EvtSercx2SystemDmaReceiveCancelNewDataNotification;

BOOLEAN EvtSercx2SystemDmaReceiveCancelNewDataNotification(
  [in] SERCX2SYSTEMDMARECEIVE SystemDmaReceive
)
{...}

Parameters

[in] SystemDmaReceive

A SERCX2SYSTEMDMARECEIVE handle to a system-DMA-receive object. The serial controller driver previously called the SerCx2SystemDmaReceiveCreate method to create this object.

Return value

The EvtSerCx2SystemDmaReceiveCancelNewDataNotification function returns TRUE if the new-data notification was successfully canceled and the serial controller driver can guarantee that this notification will not cause the SerCx2SystemDmaReceiveNewDataNotification method to be called. The function returns FALSE if the driver has already called the SerCx2SystemDmaReceiveNewDataNotification method, or is about to call this method.

Remarks

Your serial controller driver can, as an option, implement this function. If implemented, the driver registers the function in the SerCx2SystemDmaReceiveCreate call that creates the system-DMA-receive object. A driver that implements this function must also implement an EvtSerCx2SystemDmaReceiveEnableNewDataNotification event callback function.

If the associated read request times out or is canceled while a new-data notification request is pending, SerCx2 calls the EvtSerCx2SystemDmaReceiveCancelNewDataNotification function to cancel the pending notification. If this call returns FALSE, SerCx2 expects the serial controller driver to call SerCx2SystemDmaReceiveNewDataNotification; only after this call does SerCx2 call the EvtSerCx2SystemDmaReceiveCleanupTransaction function, if it is implemented, and complete the request.

To cancel the new-data notification, the EvtSerCx2SystemDmaReceiveCancelNewDataNotification function typically disables the interrupt in the serial controller that indicates that more data is available to be read from the receive FIFO. This interrupt was enabled by a previous call to the EvtSerCx2SystemDmaReceiveEnableNewDataNotification function.

For more information, see SerCx2 System-DMA-Receive Transactions.

Examples

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

EVT_SERCX2_SYSTEM_DMA_RECEIVE_CANCEL_NEW_DATA_NOTIFICATION  MySystemDmaReceiveCancelNewDataNotification;

Then, implement your callback function as follows:

_Use_decl_annotations_
BOOLEAN
  MySystemDmaReceiveCancelNewDataNotification(
    SERCX2SYSTEMDMARECEIVE  SystemDmaReceive
    )
  {...}

The EVT_SERCX2_SYSTEM_DMA_RECEIVE_CANCEL_NEW_DATA_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_SYSTEM_DMA_RECEIVE_CANCEL_NEW_DATA_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

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