SerCx2CustomReceiveTransactionCreate 函式 (sercx.h)

發行項
02/27/2024

SerCx2CustomReceiveTransactionCreate 方法會建立 custom-receive-transaction 物件，此對像是 SerCx2 (SerCx2) 用來執行自定義接收交易的版本 2。

語法

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 結構的指標。呼叫此方法之前，呼叫端必須呼叫 WDF_OBJECT_ATTRIBUTES_INIT 函式來初始化結構。此參數是選擇性的，如果序列控制器驅動程式不需要將屬性指派給物件，則可以指定為WDF_NO_OBJECT_ATTRIBUTES。如需詳細資訊，請參閱＜備註＞。

[out] CustomReceiveTransaction

這個方法將 SERCX2CUSTOMRECEIVETRANSACTION 句柄寫入新建立之自定義接收交易物件的位置指標。 SerCx2 和序列控制器驅動程式會在後續呼叫中使用這個句柄來參考這個物件。

傳回值

如果呼叫成功，這個方法會傳回STATUS_SUCCESS。可能的錯誤傳回值包括下列狀態代碼。

傳回碼	Description
STATUS_INVALID_DEVICE_REQUEST	來自先前 SerCx2CustomReceiveTransactionCreate 呼叫的 custom-receive-transaction 對象已經存在。
STATUS_INFO_LENGTH_MISMATCH	CustomReceiveTransactionConfig->Size 值不等於 sizeof (SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG) 。
STATUS_INVALID_PARAMETER	參數值無效。呼叫端必須提供有效的 EvtSerCx2CustomReceiveTransactionStart 和 EvtSerCx2CustomReceiveTransactionQueryProgress 函式指標。
STATUS_INSUFFICIENT_RESOURCES	資源不足，無法建立 custom-receive-transaction 物件。

備註

您的序列控制器驅動程式可以呼叫這個方法來建立自定義-receive-transaction 物件。 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 Transactions。