SerCx2PioReceiveCreate function (sercx.h)

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

Syntax

NTSTATUS SerCx2PioReceiveCreate(
  [in]           WDFDEVICE                  Device,
  [in]           PSERCX2_PIO_RECEIVE_CONFIG PioReceiveConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES     Attributes,
  [out]          SERCX2PIORECEIVE           *PioReceive
);

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

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

[in, optional] Attributes

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

A pointer to a location to which this method writes a SERCX2PIORECEIVE handle to the newly created PIO-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 PIO-receive object already exists from a previous SerCx2PioReceiveCreate call.
STATUS_INFO_LENGTH_MISMATCH
The Config->Size value does not equal sizeof(SERCX2_PIO_RECEIVE_CONFIG).
STATUS_INVALID_PARAMETER
The specified combination of implemented callback functions is not valid. The driver must implement the EvtSerCx2PioReceiveReadBuffer, EvtSerCx2PioReceiveEnableReadyNotification, and EvtSerCx2PioReceiveCancelReadyNotification 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-receive object. SerCx2 uses this object to perform PIO-receive transactions, which use programmed I/O (PIO) to read data received by the serial controller.

Typically, a serial controller driver calls SerCx2PioReceiveCreate 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-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 PIO-receive objects, see SERCX2PIORECEIVE. For more information about PIO-receive transactions, see SerCx2 PIO-Receive Transactions.

Requirements

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

See also

EvtCleanupCallback

EvtDestroyCallback

EvtDriverDeviceAdd

SERCX2PIORECEIVE

SERCX2_PIO_RECEIVE_CONFIG

SERCX2_PIO_RECEIVE_CONFIG_INIT

SerCx2InitializeDevice

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT