SerCx2CustomReceiveTransactionCreate function (sercx.h)

Article
10/21/2021

The SerCx2CustomReceiveTransactionCreate method creates a custom-receive-transaction object, which version 2 of the serial framework extension (SerCx2) uses to perform custom-receive transactions.

Syntax

NTSTATUS SerCx2CustomReceiveTransactionCreate(
  [in]  SERCX2CUSTOMRECEIVE                       CustomReceive,
  [in]  PSERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG CustomReceiveTransactionConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES                    Attributes,
  [out] SERCX2CUSTOMRECEIVETRANSACTION            *CustomReceiveTransaction
);

Parameters

[in] CustomReceive

A SERCX2CUSTOMRECEIVE handle to a custom-receive object. The serial controller driver previously called the SerCx2CustomReceiveCreate method to create this object.

[in] CustomReceiveTransactionConfig

A pointer to a SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG structure. Before calling this method, the caller must call the SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG_INIT function to initialize the structure. This structure contains pointers to a set of event callback routines that are implemented by the serial controller driver. SerCx2 calls these functions to do an I/O transaction that uses the custom data-transfer mechanism to read data received by the serial controller.

[in] Attributes

A pointer to a WDF_OBJECT_ATTRIBUTES structure that describes the attributes to assign to the new custom-receive-transaction object. Before calling this method, the caller must call the WDF_OBJECT_ATTRIBUTES_INIT function to initialize the structure. This parameter is optional and can be specified as WDF_NO_OBJECT_ATTRIBUTES if the serial controller driver does not need to assign attributes to the object. For more information, see Remarks.

[out] CustomReceiveTransaction

A pointer to a location to which this method writes a SERCX2CUSTOMRECEIVETRANSACTION handle to the newly created custom-receive-transaction object. SerCx2 and the serial controller driver use this handle in subsequent calls to refer to this object.

Return value

This method returns STATUS_SUCCESS if the call is successful. Possible error return values include the following status codes.

Return code	Description
STATUS_INVALID_DEVICE_REQUEST	A custom-receive-transaction object already exists from a previous SerCx2CustomReceiveTransactionCreate call.
STATUS_INFO_LENGTH_MISMATCH	The CustomReceiveTransactionConfig->Size value does not equal sizeof(SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG).
STATUS_INVALID_PARAMETER	A parameter value is not valid. The caller must supply valid EvtSerCx2CustomReceiveTransactionStart and EvtSerCx2CustomReceiveTransactionQueryProgress function pointers.
STATUS_INSUFFICIENT_RESOURCES	Insufficient resources are available to create the custom-receive-transaction object.

Remarks

Your serial controller driver can call this method to create a custom-receive-transaction object. SerCx2 uses this object to manage custom-receive transactions, which are I/O transactions that use a custom data-transfer mechanism to read data received by the serial controller.

As an option, a serial controller driver can use the Attributes parameter to create a context for the custom-receive object, and to supply pointers to EvtCleanupCallback and EvtDestroyCallback functions that are called to prepare the object for deletion. For more information, see WDF_OBJECT_ATTRIBUTES.

If the Attributes parameter points to a WDF_OBJECT_ATTRIBUTES structure, the caller must not overwrite the values that the WDF_OBJECT_ATTRIBUTES_INIT initialization function writes to the ParentObject, ExecutionLevel, and SynchronizationScope members of this structure.

If the specified combination of implemented callback functions is not valid, the SerCx2CustomReceiveTransactionCreate call fails and returns STATUS_INVALID_PARAMETER.

For more information about creating custom-receive-transaction objects, see SERCX2CUSTOMRECEIVETRANSACTION. For more information about custom-receive transactions, see SerCx2 Custom-Receive Transactions.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 8.1.
Target Platform	Universal
Header	sercx.h
IRQL	PASSIVE_LEVEL