EVT_SERCX2_CUSTOM_RECEIVE_TRANSMIT_QUERY_PROGRESS callback function

Article
06/27/2017

The EvtSerCx2CustomReceiveTransactionQueryProgress event callback function is called by version 2 of the serial framework extension (SerCx2) to check whether progress is being made on the current custom-receive transaction.

Syntax

EVT_SERCX2_CUSTOM_RECEIVE_TRANSMIT_QUERY_PROGRESS EvtSerCx2CustomReceiveTransactionQueryProgress;

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

Parameters

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

Return value

None

Remarks

Your serial controller driver must implement this function if it creates a custom-receive-transaction object. The driver registers the function in the call to the SerCx2CustomReceiveTransactionCreate method that creates this object.

In response to a call to the EvtSerCx2CustomReceiveTransactionQueryProgress function, the serial controller driver must call the SerCx2CustomReceiveTransactionReportProgress method to report whether one or more bytes of data have been received since the previous call to SerCx2CustomReceiveTransactionReportProgress or since the custom-receive transaction started (for the first call to SerCx2CustomReceiveTransactionReportProgress).

To manage interval time-outs, SerCx2 periodically calls the EvtSerCx2CustomReceiveTransactionQueryProgress function to determine whether any data has been transferred since the previous call to this function. For more information, see SerCx2 Custom-Receive Transactions.

Examples

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

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_QUERY_PROGRESS  MyCustomReceiveTransactionQueryProgress;

Then, implement your callback function as follows:

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

The EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_QUERY_PROGRESS 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_QUERY_PROGRESS 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