Skip to content

Latest commit

 

History

History
131 lines (84 loc) · 6.93 KB

nc-sercx-evt_sercx2_custom_receive_transaction_initialize.md

File metadata and controls

131 lines (84 loc) · 6.93 KB
Raw
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_CUSTOM_RECEIVE_TRANSACTION_INITIALIZE
EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_INITIALIZE (sercx.h)
The EvtSerCx2CustomReceiveTransactionInitialize event callback function is called by version 2 of the serial framework extension (SerCx2) to prepare the serial controller hardware to perform a new custom-receive transaction.
serports\evtsercx2customreceivetransactioninitialize.htm
serports
04/23/2018
EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_INITIALIZE callback function
2/EvtSerCx2CustomReceiveTransactionInitialize, EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_INITIALIZE, EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_INITIALIZE callback, EvtSerCx2CustomReceiveTransactionInitialize, EvtSerCx2CustomReceiveTransactionInitialize callback function [Serial Ports], serports.evtsercx2customreceivetransactioninitialize
sercx.h
Desktop
Available starting with Windows 8.1.
Called at IRQL <= DISPATCH_LEVEL.
Windows
EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_INITIALIZE
sercx/EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_INITIALIZE
APIRef
kbSyntax
UserDefined
2.0\Sercx.h
EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_INITIALIZE

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_INITIALIZE callback function

-description

The EvtSerCx2CustomReceiveTransactionInitialize event callback function is called by version 2 of the serial framework extension (SerCx2) to prepare the serial controller hardware to perform a new custom-receive transaction.

-parameters

-param CustomReceiveTransaction [in]

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

-param Mdl [in]

A pointer to an MDL that describes the memory pages that are spanned by the read buffer for the custom-receive transaction. The scatter/gather list for the DMA transfer will use the region of this memory that is specified by the Offset and Length parameters.

-param Offset [in]

The starting offset for the data transfer. This parameter is a byte offset from the start of the buffer region described by the MDL. If the MDL specifies a total of N bytes of buffer space, possible values of Offset are in the range 0 to N–1.

-param Length [in]

The size, in bytes, of the data transfer. If the MDL specifies a total of N bytes of buffer space, possible values of Length are in the range 1 to N–Offset.

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

Your driver should implement an EvtSerCx2CustomReceiveTransactionInitialize function if it needs to initialize the serial controller and associated hardware in preparation for a new custom-receive transaction. SerCx2 calls this function, if it is implemented, before starting the custom-receive transaction. In response to this call, the serial controller driver must call the SerCx2CustomReceiveTransactionInitializeComplete method to notify SerCx2 after the initialization is finished.

For more information, see SerCx2 Custom-Receive Transactions.

Examples

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

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_INITIALIZE  MyCustomReceiveTransactionInitialize;

Then, implement your callback function as follows:

_Use_decl_annotations_
VOID
  MyCustomReceiveTransactionInitialize(
    SERCX2CUSTOMRECEIVETRANSACTION  CustomReceiveTransaction,
    WDFREQUEST  Request,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  Length
    )
  {...}

The EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_INITIALIZE 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_INITIALIZE 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.

-see-also

IRP_MJ_READ

MDL

SERCX2CUSTOMRECEIVETRANSACTION

SerCx2CustomReceiveTransactionCreate

SerCx2CustomReceiveTransactionInitializeComplete