SerCx2CustomReceiveTransactionCreate 函数 (sercx.h)

项目
08/07/2023

SerCx2CustomReceiveTransactionCreate 方法创建一个 custom-receive-transaction 对象，该对象的串行框架扩展版本 2 (SerCx2) 用于执行自定义接收事务。

语法

NTSTATUS SerCx2CustomReceiveTransactionCreate(
  [in]  SERCX2CUSTOMRECEIVE                       CustomReceive,
  [in]  PSERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG CustomReceiveTransactionConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES                    Attributes,
  [out] SERCX2CUSTOMRECEIVETRANSACTION            *CustomReceiveTransaction
);

参数

[in] CustomReceive

自定义接收对象的 SERCX2CUSTOMRECEIVE 句柄。串行控制器驱动程序之前调用 SerCx2CustomReceiveCreate 方法来创建此对象。

[in] CustomReceiveTransactionConfig

指向 SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG 结构的指针。在调用此方法之前，调用方必须调用 SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG_INIT 函数来初始化结构。此结构包含指向由串行控制器驱动程序实现的一组事件回调例程的指针。 SerCx2 调用这些函数来执行 I/O 事务，该事务使用自定义数据传输机制读取串行控制器接收的数据。

[in] Attributes

指向 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构描述要分配给新的 custom-receive-transaction 对象的属性。在调用此方法之前，调用方必须调用 WDF_OBJECT_ATTRIBUTES_INIT 函数来初始化结构。此参数是可选的，如果串行控制器驱动程序不需要向对象分配属性，则可以指定为WDF_NO_OBJECT_ATTRIBUTES。有关详细信息，请参阅“备注”。

[out] CustomReceiveTransaction

指向将 SERCX2CUSTOMRECEIVETRANSACTION 句柄写入新创建的自定义接收事务对象的位置的指针。 SerCx2 和串行控制器驱动程序在后续调用中使用此句柄来引用此对象。

返回值

如果调用成功，此方法将返回STATUS_SUCCESS。可能的错误返回值包括以下状态代码。

返回代码	说明
STATUS_INVALID_DEVICE_REQUEST	以前的 SerCx2CustomReceiveTransactionCreate 调用中已存在 custom-receive-transaction 对象。
STATUS_INFO_LENGTH_MISMATCH	CustomReceiveTransactionConfig->Size 值不等于 (SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG) 的大小。
STATUS_INVALID_PARAMETER	参数值无效。调用方必须提供有效的 EvtSerCx2CustomReceiveTransactionStart 和 EvtSerCx2CustomReceiveTransactionQueryProgress 函数指针。
STATUS_INSUFFICIENT_RESOURCES	没有足够的资源可用于创建自定义接收事务对象。

注解

串行控制器驱动程序可以调用此方法来创建自定义接收事务对象。 SerCx2 使用此对象来管理自定义接收事务，即使用自定义数据传输机制读取串行控制器接收的数据的 I/O 事务。

作为选项，串行控制器驱动程序可以使用 Attributes 参数为自定义接收对象创建上下文，并提供指向 EvtCleanupCallback 和 EvtDestroyCallback 函数的指针，这些函数被调用以准备要删除的对象。有关详细信息，请参阅 WDF_OBJECT_ATTRIBUTES。

如果 Attributes 参数指向 WDF_OBJECT_ATTRIBUTES 结构，则调用方不得覆盖 WDF_OBJECT_ATTRIBUTES_INIT 初始化函数写入此结构的 ParentObject、 ExecutionLevel 和 SynchronizationScope 成员的值。

如果实现的回调函数的指定组合无效， SerCx2CustomReceiveTransactionCreate 调用将失败并返回STATUS_INVALID_PARAMETER。

有关创建自定义接收事务对象的详细信息，请参阅 SERCX2CUSTOMRECEIVETRANSACTION。有关自定义接收事务的详细信息，请参阅 SerCx2 Custom-Receive 事务。