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 |
|---|---|
|
A PIO-receive object already exists from a previous SerCx2PioReceiveCreate call. |
|
The Config->Size value does not equal sizeof(SERCX2_PIO_RECEIVE_CONFIG). |
|
The specified combination of implemented callback functions is not valid. The driver must implement the EvtSerCx2PioReceiveReadBuffer, EvtSerCx2PioReceiveEnableReadyNotification, and EvtSerCx2PioReceiveCancelReadyNotification functions. |
|
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 |