SerCx2CustomReceiveCreate function (sercx.h)

Article
10/21/2021

The SerCx2CustomReceiveCreate method creates a custom-receive object, which version 2 of the serial framework extension (SerCx2) uses to read receive data from the serial controller by means of a custom data-transfer mechanism.

Syntax

NTSTATUS SerCx2CustomReceiveCreate(
  [in]  WDFDEVICE                     Device,
  [in]  PSERCX2_CUSTOM_RECEIVE_CONFIG CustomReceiveConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out] SERCX2CUSTOMRECEIVE           *CustomReceive
);

Parameters

[in] Device

A WDFDEVICE handle to the framework device object that represents the serial controller. The serial controller driver created this object in its EvtDriverDeviceAdd callback function. For more information, see SerCx2InitializeDevice.

[in] CustomReceiveConfig

A pointer to a SERCX2_CUSTOM_RECEIVE_CONFIG structure. Before calling this method, the caller must call the SERCX2_CUSTOM_RECEIVE_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 perform custom-receive transactions.

[in] Attributes

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

A pointer to a location to which this method writes a SERCX2CUSTOMRECEIVE handle to the newly created custom-receive 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 object already exists from a previous SerCx2CustomReceiveCreate call; or a system-DMA-receive object exists from a previous SerCx2CustomReceiveCreate call; or a system-DMA-transmit object exists from a previous SerCx2CustomTransmitCreate call; or SerCx2PioReceiveCreate has not yet been called to create a PIO-receive object.
STATUS_INVALID_PARAMETER	A parameter value is not valid.
STATUS_INFO_LENGTH_MISMATCH	The Config->Size value does not equal sizeof(SERCX2_CUSTOM_RECEIVE_CONFIG).
STATUS_INSUFFICIENT_RESOURCES	Insufficient resources are available to create the custom-receive object.

Remarks

This method is called by the serial controller driver to create a custom-receive object. SerCx2 uses this object to do custom-receive transactions, which are transactions that use a custom data-transfer mechanism to read data received by the serial controller.

A serial controller driver must successfully call the SerCx2InitializeDevice and SerCx2PioReceiveCreate methods before calling SerCx2CustomReceiveCreate.

Before calling SerCx2CustomReceiveCreate, the serial controller driver must call the SERCX2_CUSTOM_RECEIVE_CONFIG_INIT function to initialize the SERCX2_CUSTOM_RECEIVE_CONFIG structure pointed to by CustomReceiveConfig. This function sets the following members of the structure to zero:

Alignment
MinimumTransactionLength
MaximumTransactionLength
MinimumTransferUnit
Exclusive

If necessary, the serial controller driver can set any of these members to nonzero values after the initialization function returns. However, for convenience, SerCx2CustomReceiveCreate uses the following default values if these members are zero:

If Alignment is zero, SerCx2 sets the data alignment value to one, which means the read buffer can start on an arbitrary byte boundary in memory.
If MinimumTransactionLength is zero, SerCx2 sets the minimum transaction length to one byte.
If MaximumTransactionLength is zero, SerCx2 sets the maximum transaction length to ((ULONG)-1).
If MinimumTransferUnit is zero, SerCx2 sets the minimum transfer unit to one byte.
If Exclusive is zero (FALSE), exclusive mode is disabled.

If the calling driver sets Exclusive to TRUE, the MinimumTransferUnit, Alignment, and MinimumTransactionLength members must be zero. For more information, see SERCX2_CUSTOM_RECEIVE_CONFIG.

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.

For more information about creating custom-receive objects, see SERCX2CUSTOMRECEIVE. 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