EVT_SERCX2_SYSTEM_DMA_RECEIVE_CANCEL_NEW_DATA_NOTIFICATION callback function

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

SystemDmaReceive [in]

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

Target platform

Desktop

Version

Available starting with Windows 8.1.

Header

2.0\Sercx.h

IRQL

Called at IRQL <= DISPATCH_LEVEL.

See also

EvtSerCx2SystemDmaReceiveEnableNewDataNotification
SERCX2SYSTEMDMARECEIVE
SerCx2SystemDmaReceiveCreate
SerCx2SystemDmaReceiveNewDataNotification

 

 

Send comments about this topic to Microsoft

Show: