SerCx2PioTransmitCreate function (sercx.h)

Article
10/21/2021

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

Syntax

NTSTATUS SerCx2PioTransmitCreate(
  [in]           WDFDEVICE                   Device,
  [in]           PSERCX2_PIO_TRANSMIT_CONFIG PioTransmitConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES      Attributes,
  [out]          SERCX2PIOTRANSMIT           *PioTransmit
);

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] PioTransmitConfig

A pointer to a SERCX2_PIO_TRANSMIT_CONFIG structure. Before calling this method, the caller must call the SERCX2_PIO_TRANSMIT_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 PIO-transmit transactions.

[in, optional] Attributes

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

A pointer to a location to which this method writes a SERCX2PIOTRANSMIT handle to the newly created PIO-transmit 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 PIO-transmit object already exists from a previous SerCx2PioTransmitCreate call.
STATUS_INFO_LENGTH_MISMATCH	The Config->Size value does not equal sizeof(SERCX2_PIO_TRANSMIT_CONFIG).
STATUS_INVALID_PARAMETER	The specified combination of implemented callback functions is not valid. The driver must implement the EvtSerCx2PioTransmitWriteBuffer, EvtSerCx2PioTransmitEnableReadyNotification, and EvtSerCx2PioTransmitCancelReadyNotification functions. The driver must implement either all three or none of the EvtSerCx2PioTransmitDrainFifo, EvtSerCx2PioTransmitCancelDrainFifo, and EvtSerCx2PioTransmitPurgeFifo functions.
STATUS_INSUFFICIENT_RESOURCES	Insufficient resources are available to perform the requested operation.

Remarks

Your serial controller driver calls this method to create a PIO-transmit object. SerCx2 uses this object to perform PIO-transmit transactions, which are transactions that use programmed I/O (PIO) to write data to the serial controller to be transmitted.

Typically, a serial controller driver calls SerCx2PioTransmitCreate from its EvtDriverDeviceAdd function. The driver must call this method only after it successfully calls the SerCx2InitializeDevice method.

As an option, a serial controller driver can use the Attributes parameter to create a context for the PIO-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.

For more information about creating PIO-transmit objects, see SERCX2PIOTRANSMIT. For more information about PIO-transmit operations, see SerCx2 PIO-Transmit Transactions.

Requirements

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