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_SYSTEM_DMA_RECEIVE_ENABLE_NEW_DATA_NOTIFICATION

EVT_SERCX2_SYSTEM_DMA_RECEIVE_ENABLE_NEW_DATA_NOTIFICATION (sercx.h)

The EvtSerCx2SystemDmaReceiveEnableNewDataNotification event callback function is called by version 2 of the serial framework extension (SerCx2) to enable the serial controller driver to notify SerCx2 when the serial controller receives new data.

serports\evtsercx2systemdmareceiveenablenewdatanotification.htm

serports

04/23/2018

EVT_SERCX2_SYSTEM_DMA_RECEIVE_ENABLE_NEW_DATA_NOTIFICATION callback function

2/EvtSerCx2SystemDmaReceiveEnableNewDataNotification, EVT_SERCX2_SYSTEM_DMA_RECEIVE_ENABLE_NEW_DATA_NOTIFICATION, EVT_SERCX2_SYSTEM_DMA_RECEIVE_ENABLE_NEW_DATA_NOTIFICATION callback, EvtSerCx2SystemDmaReceiveEnableNewDataNotification, EvtSerCx2SystemDmaReceiveEnableNewDataNotification callback function [Serial Ports], serports.evtsercx2systemdmareceiveenablenewdatanotification

sercx.h

Desktop

Available starting with Windows 8.1.

Called at IRQL <= DISPATCH_LEVEL.

Windows

EVT_SERCX2_SYSTEM_DMA_RECEIVE_ENABLE_NEW_DATA_NOTIFICATION

sercx/EVT_SERCX2_SYSTEM_DMA_RECEIVE_ENABLE_NEW_DATA_NOTIFICATION

APIRef

kbSyntax

UserDefined

2.0\Sercx.h

EVT_SERCX2_SYSTEM_DMA_RECEIVE_ENABLE_NEW_DATA_NOTIFICATION

EVT_SERCX2_SYSTEM_DMA_RECEIVE_ENABLE_NEW_DATA_NOTIFICATION callback function

-description

The EvtSerCx2SystemDmaReceiveEnableNewDataNotification event callback function is called by version 2 of the serial framework extension (SerCx2) to enable the serial controller driver to notify SerCx2 when the serial controller receives new data.

-parameters

-param SystemDmaReceive [in]

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

-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.

After the EvtSerCx2SystemDmaReceiveEnableNewDataNotification function is called to enable a new-data notification for a system-DMA-receive transaction, the serial controller driver must call the SerCx2SystemDmaReceiveNewDataNotification method to notify SerCx2 when the driver detects that one or more bytes of received data either are ready to be transferred or have already been transferred by the system DMA controller.

The new-data notification enabled by the EvtSerCx2SystemDmaReceiveEnableNewDataNotification function is a one-shot notification. After this function is called and the serial controller driver sends a new-data notification to SerCx2, no further notification is sent until SerCx2 calls the function again to enable another notification.

The EvtSerCx2SystemDmaReceiveEnableNewDataNotification function typically enables an interrupt to be triggered when the serial controller receives data from the peripheral device.

No more than one new-data notification can be pending at a time. After SerCx2 calls the EvtSerCx2SystemDmaReceiveEnableNewDataNotification function to enable a new-data notification, SerCx2 does not call this function again until the controller driver calls SerCx2SystemDmaReceiveNewDataNotification.

A pending new-data notification can be canceled if the associated read request times out or is canceled. To cancel a new-data notification for a system-DMA-receive transaction, SerCx2 calls the EvtSerCx2SystemDmaReceiveCancelNewDataNotification event callback function. A driver that implements an EvtSerCx2SystemDmaReceiveEnableNewDataNotification function must also implement an EvtSerCx2SystemDmaReceiveCancelNewDataNotification function.

SerCx2 uses new-data notifications to efficiently manage interval time-outs that occur during the handling of read requests that are processed as system-DMA-receive transactions.

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

Examples

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

EVT_SERCX2_SYSTEM_DMA_RECEIVE_ENABLE_NEW_DATA_NOTIFICATION  MySystemDmaReceiveEnableNewDataNotification;

Then, implement your callback function as follows:

_Use_decl_annotations_
VOID
  MySystemDmaReceiveEnableNewDataNotification(
    SERCX2SYSTEMDMARECEIVE  SystemDmaReceive
    )
  {...}

The EVT_SERCX2_SYSTEM_DMA_RECEIVE_ENABLE_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_ENABLE_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.