EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_NEW_DATA_NOTIFICATION callback function

Article
06/27/2017

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

Syntax

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_NEW_DATA_NOTIFICATION EvtSerCx2CustomReceiveTransactionEnableNewDataNotification;

VOID EvtSerCx2CustomReceiveTransactionEnableNewDataNotification(
  _In_ SERCX2CUSTOMRECEIVETRANSACTION CustomReceiveTransaction
)
{ ... }

Parameters

CustomReceiveTransaction [in]
A SERCX2CUSTOMRECEIVETRANSACTION handle to a custom-receive object. The serial controller driver previously called the SerCx2CustomReceiveTransactionCreate method to create this object.

Return value

None.

Remarks

Your serial controller driver can, as an option, implement this function. If implemented, the driver registers the function in the SerCx2CustomReceiveTransactionCreate call that creates the custom-receive object.

After this function is called to enable a new-data notification for a custom-receive transaction, the serial controller driver must call the SerCx2CustomReceiveTransactionNewDataNotification 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 custom data-transfer mechanism.

The new-data notification enabled by the EvtSerCx2CustomReceiveTransactionEnableNewDataNotification 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 EvtSerCx2CustomReceiveTransactionEnableNewDataNotification 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 enabled at a time. After SerCx2 calls the EvtSerCx2CustomReceiveTransactionEnableNewDataNotification function during a custom-receive transaction, SerCx2 does not call this function again until after the controller driver calls SerCx2CustomReceiveTransactionNewDataNotification.

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

For more information, see SerCx2 Custom-Receive Transactions.

Examples

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

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_NEW_DATA_NOTIFICATION  MyCustomReceiveTransactionEnableNewDataNotification;

Then, implement your callback function as follows:

_Use_decl_annotations_
VOID
  MyCustomReceiveTransactionEnableNewDataNotification(
    SERCX2CUSTOMRECEIVETRANSACTION  CustomReceiveTransaction
    )
  {...}

The EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_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_CUSTOM_RECEIVE_TRANSACTION_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.

Partager via