SerCx2PioTransmitCreate 函式 (sercx.h)

發行項
02/26/2024

SerCx2PioTransmitCreate 方法會建立 PIO 傳輸物件，此物件是 SerCx2 (SerCx2) 用來執行 PIO 傳輸交易的序列架構延伸模組第 2 版。

語法

NTSTATUS SerCx2PioTransmitCreate(
  [in]           WDFDEVICE                   Device,
  [in]           PSERCX2_PIO_TRANSMIT_CONFIG PioTransmitConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES      Attributes,
  [out]          SERCX2PIOTRANSMIT           *PioTransmit
);

參數

[in] Device

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

[in] PioTransmitConfig

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

[in, optional] Attributes

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

[out] PioTransmit

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

傳回值

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

傳回碼	Description
STATUS_INVALID_DEVICE_REQUEST	PIO 傳輸物件已存在於先前的 SerCx2PioTransmitCreate 呼叫中。
STATUS_INFO_LENGTH_MISMATCH	[設定->大小] 值不等於大小 (SERCX2_PIO_TRANSMIT_CONFIG) 。
STATUS_INVALID_PARAMETER	實作回呼函式的指定組合無效。驅動程式必須實作 EvtSerCx2PioTransmitWriteBuffer、 EvtSerCx2PioTransmitEnableReadyNotification 和 EvtSerCx2PioTransmitCancelReadyNotification 函式。驅動程式必須實作所有三個或無 EvtSerCx2PioTransmitDrainFifo、 EvtSerCx2PioTransmitCancelDrainFifo 和 EvtSerCx2PioTransmitPurgeFifo 函式。
STATUS_INSUFFICIENT_RESOURCES	資源不足，無法執行要求的作業。

備註

您的序列控制器驅動程式會呼叫這個方法來建立 PIO 傳輸物件。 SerCx2 會使用此物件來執行 PIO 傳輸交易，也就是使用程式化 I/O (PIO 的交易，) 將數據寫入要傳輸的序列控制器。

一般而言，序列控制器驅動程式會從其 EvtDriverDeviceAdd 函式呼叫 SerCx2PioTransmitCreate。只有在驅動程式成功呼叫 SerCx2InitializeDevice 方法之後，才能呼叫這個方法。

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

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

如需建立 PIO 傳輸對象的詳細資訊，請參閱 SERCX2PIOTRANSMIT。如需 PIO 傳輸作業的詳細資訊，請參閱 SerCx2 PIO-Transmit Transactions。