SerCx2CustomTransmitCreate 函式 (sercx.h)

發行項
02/26/2024

SerCx2CustomTransmitCreate 方法會建立自定義傳輸物件，該對像是串行架構延伸模組的第 2 版， (SerCx2) 會利用自定義數據傳輸機制，將數據寫入序列控制器。

語法

NTSTATUS SerCx2CustomTransmitCreate(
  [in]  WDFDEVICE                      Device,
  [in]  PSERCX2_CUSTOM_TRANSMIT_CONFIG CustomTransmitConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES         Attributes,
  [out] SERCX2CUSTOMTRANSMIT           *CustomTransmit
);

參數

[in] Device

代表序列控制器之架構裝置物件的WDFDEVICE句柄。序列控制器驅動程式在其 EvtDriverDeviceAdd 回呼函式中建立了這個物件。如需詳細資訊，請參閱 SerCx2InitializeDevice。

[in] CustomTransmitConfig

SERCX2_CUSTOM_TRANSMIT_CONFIG 結構的指標。呼叫這個方法之前，呼叫端必須呼叫 SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT 函式來初始化結構。這個結構包含序列控制器驅動程式所實作之一組事件回呼例程的指標。 SerCx2 會呼叫這些函式來執行自定義傳輸交易。

[in] Attributes

WDF_OBJECT_ATTRIBUTES 結構的指標，描述要指派給新自定義傳輸對象的屬性。呼叫這個方法之前，呼叫端必須呼叫 WDF_OBJECT_ATTRIBUTES_INIT 函式來初始化結構。這個參數是選擇性的，而且如果序列控制器驅動程式不需要將屬性指派給物件，則可以指定為WDF_NO_OBJECT_ATTRIBUTES。如需詳細資訊，請參閱＜備註＞。

[out] CustomTransmit

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

傳回值

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

傳回碼	Description
STATUS_INVALID_DEVICE_REQUEST	來自先前 SerCx2CustomTransmitCreate 呼叫的自定義傳輸對象已經存在;或來自先前 SerCx2SystemDmaTransmitCreate 呼叫的 system-DMA-transmit 物件;或來自先前 SerCx2SystemDmaTransmitCreate 呼叫的 system-DMA-transmit 物件;或 SerCx2PioTransmitCreate 尚未呼叫以建立 PIO 傳輸物件。
STATUS_INVALID_PARAMETER	參數值無效。
STATUS_INFO_LENGTH_MISMATCH	[設定->大小] 值不等於 (SERCX2_CUSTOM_TRANSMIT_CONFIG) 。
STATUS_INSUFFICIENT_RESOURCES	資源不足，無法建立自定義傳輸物件。

備註

這個方法是由序列控制器驅動程式呼叫，以建立自定義傳輸物件。 SerCx2 會使用此物件來執行自定義傳輸交易，這是使用自定義數據傳輸機制將數據傳輸至序列控制器的交易。

序列控制器驅動程序必須先成功呼叫 SerCx2InitializeDevice 和 SerCx2PioTransmitCreate 方法，再呼叫 SerCx2CustomTransmitCreate。

在呼叫 SerCx2CustomTransmitCreate 之前，序列控制器驅動程式必須呼叫 SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT 函式，以初始化 CustomTransmitConfig 指向的SERCX2_CUSTOM_TRANSMIT_CONFIG結構。此函式會將結構的下列成員設定為零：

對齊
MinimumTransactionLength
MaximumTransactionLength
MinimumTransferUnit
排除

如有必要，序列控制器驅動程式可以在初始化函式傳回之後，將這些成員的任何一個設定為非零值。不過，為了方便起見，如果這些成員為零， SerCx2CustomTransmitCreate 會使用下列預設值：

如果 Alignment 為零，SerCx2 會將數據對齊值設定為 1，這表示寫入緩衝區可以從記憶體中的任意位元組界限開始。
如果 MinimumTransactionLength 為零，SerCx2 會將交易長度下限設定為一個字節。
如果 MaximumTransactionLength 為零，SerCx2 會將交易長度上限設定為 ( (ULONG) -1) 。
如果 MinimumTransferUnit 為零，SerCx2 會將最小傳輸單位設定為一個字節。
如果 Exclusive 為零 (FALSE) ，則會停用獨佔模式。

如果呼叫驅動程式將 Exclusive 設定為 TRUE，MinimumTransferUnit、Alignment 和 MinimumTransactionLength 成員必須為零。如需詳細資訊，請參閱 SERCX2_CUSTOM_TRANSMIT_CONFIG。

作為選項，序列控制器驅動程式可以使用 Attributes 參數來建立自定義傳輸對象的內容，並提供指向 EvtCleanupCallback 和 EvtDestroyCallback 函式的指標，這些函式會呼叫以準備物件以進行刪除。如需詳細資訊，請參閱 WDF_OBJECT_ATTRIBUTES。

如果 Attributes 參數指向 WDF_OBJECT_ATTRIBUTES 結構，呼叫端不得覆寫 WDF_OBJECT_ATTRIBUTES_INIT 初始化函式寫入至此結構的 ParentObject、 ExecutionLevel 和 SynchronizationScope 成員的值。

如需建立自定義傳輸對象的詳細資訊，請參閱 SERCX2CUSTOMTRANSMIT。如需自定義傳輸交易的詳細資訊，請參閱 SerCx2 Custom-Transmit 交易。