DMA_COMPLETION_ROUTINE回呼函式 (wdm.h)

DmaCompletionRoutine 回呼例程會通知驅動程式先前要求完成此傳輸的系統 DMA 傳輸。

語法

DMA_COMPLETION_ROUTINE DmaCompletionRoutine;

void DmaCompletionRoutine(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PVOID CompletionContext,
  [in] DMA_COMPLETION_STATUS Status
)
{...}

參數

[in] DmaAdapter

DMA_ADAPTER 結構的指標。 這個結構是代表驅動程式系統 DMA 通道的配接器物件。

[in] DeviceObject

DEVICE_OBJECT 結構的指標。 此結構是 PDO (實體裝置物件，) ，代表所要求 DMA 作業的目標裝置。

[in] CompletionContext

DmaCompletionRoutine 例程之驅動程序決定內容的指標。 此內容是驅動程式先前傳遞至啟動系統 DMA 傳輸之 MapTransferEx 呼叫的 CompletionContext 參數值。

[in] Status

DMA 傳輸的完成狀態。 此參數是 DMA_COMPLETION_STATUS 列舉值，指出 DMA 傳輸是否已順利完成。

傳回值

無

備註

作為選項，驅動程式可以實作 DmaCompletionRoutine 例程。 當驅動程式要求系統 DMA 傳輸時，驅動程式可以使用要求來提供此例程的指標。 DMA 傳輸完成之後，會自動呼叫 DmaCompletionRoutine 例程來通知驅動程式。

只有在驅動程式要求的 DMA 傳輸使用系統 DMA 控制器，在 DMA 傳輸完成之後，才會呼叫驅動程式的 DmaCompletionRoutine 例程。 使用總線主機 DMA 裝置或使用系統 DMA 控制器而不會產生中斷的驅動程式，必須使用其他方法來判斷 DMA 傳輸何時完成。 例如，此驅動程式可能會使用定時器中斷定期輪詢 DMA 傳輸的狀態。

驅動程式可以提供 DmaCompletionRoutine 例程的指標，做為 MapTransferEx 例程的選擇性參數。

範例

若要定義 DmaCompletionRoutine 回呼例程，您必須先提供函式宣告來識別您要定義的回呼例程類型。 Windows 提供一組驅動程式的回呼函式類型。 使用回呼函式類型宣告函式有助於 驅動程式的程式代碼分析、 靜態驅動程式驗證器 (SDV) ，以及其他驗證工具尋找錯誤，而且這是撰寫 Windows 操作系統驅動程式的需求。

例如，若要定義名為 MyDmaCompletionRoutine的 DmaCompletionRoutine 回呼例程，請使用 DMA_COMPLETION_ROUTINE 類型，如下列程式代碼範例所示：

DMA_COMPLETION_ROUTINE MyDmaCompletionRoutine;

然後，實作回呼例程，如下所示：

_Use_decl_annotations_
VOID
  MyDmaCompletionRoutine(
    PDMA_ADAPTER DmaAdapter,
    PDEVICE_OBJECT DeviceObject,
    PVOID CompletionContext,
    DMA_COMPLETION_STATUS Status
    )
  {
      // Function body
  }

DMA_COMPLETION_ROUTINE函式類型定義於 Wdm.h 頭檔中。 若要在執行程式代碼分析工具時更精確地識別錯誤，請務必將 _Use_decl_annotations_ 批註新增至函式定義。 註釋 _Use_decl_annotations_ 可確保使用頭檔中套用至DMA_COMPLETION_ROUTINE函式類型的註釋。 如需函數宣告需求的詳細資訊，請參閱 使用WDM驅動程式的函式角色類型來宣告函式。 如需_Use_decl_annotations_的詳細資訊，請參閱 標註函式行為。

規格需求

另請參閱

BuildScatterGatherListEx

DEVICE_OBJECT

DMA_ADAPTER

DMA_COMPLETION_STATUS

DMA_OPERATIONS

GetScatterGatherListEx

MapTransferEx