SerCx2CustomTransmitTransactionCreate function (sercx.h)

Article
10/21/2021

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

Syntax

NTSTATUS SerCx2CustomTransmitTransactionCreate(
  [in]  SERCX2CUSTOMTRANSMIT                       CustomTransmit,
  [in]  PSERCX2_CUSTOM_TRANSMIT_TRANSACTION_CONFIG CustomTransmitTransactionConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES                     Attributes,
  [out] SERCX2CUSTOMTRANSMITTRANSACTION            *CustomTransmitTransaction
);

Parameters

[in] CustomTransmit

A SERCX2CUSTOMTRANSMIT handle to a custom-transmit object. The serial controller driver previously called the SerCx2CustomTransmitCreate method to create this object.

[in] CustomTransmitTransactionConfig

A pointer to a SERCX2_CUSTOM_TRANSMIT_TRANSACTION_CONFIG structure. Before calling this method, the caller must call the SERCX2_CUSTOM_TRANSMIT_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 write data to the serial controller to be transmitted.

[in] Attributes

A pointer to a WDF_OBJECT_ATTRIBUTES structure that describes the attributes to assign to the new custom-transmit-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] CustomTransmitTransaction

A pointer to a location to which this method writes a SERCX2CUSTOMTRANSMITTRANSACTION handle to the newly created custom-transmit-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-transmit-transaction object already exists from a previous SerCx2CustomTransmitTransactionCreate call.
STATUS_INFO_LENGTH_MISMATCH	The CustomTransmitTransactionConfig->Size value does not equal sizeof(SERCX2_CUSTOM_TRANSMIT_TRANSACTION_CONFIG).
STATUS_INVALID_PARAMETER	A parameter value is not valid. The caller must supply a valid EvtSerCx2CustomTransmitTransactionStart function pointer.
STATUS_INSUFFICIENT_RESOURCES	Insufficient resources are available to create the custom-transmit-transaction object.

Remarks

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

As an option, a serial controller driver can use the Attributes parameter to create a context for the custom-transmit 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, SerCx2CustomTransmitTransactionCreate fails and returns STATUS_INVALID_PARAMETER.

For more information about creating custom-transmit-transaction objects, see SERCX2CUSTOMTRANSMITTRANSACTION. For more information about custom-transmit transactions, see SerCx2 Custom-Transmit Transactions.

Requirements

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