PMAP_TRANSFER_EX回呼函式 （wdm.h）
MapTransferEx 例程會設定對應快取器，以將散佈/收集清單中的實體地址對應至執行 DMA 傳輸所需的邏輯位址。
語法
PMAP_TRANSFER_EX PmapTransferEx;
NTSTATUS PmapTransferEx(
[in] PDMA_ADAPTER DmaAdapter,
[in] PMDL Mdl,
[in] PVOID MapRegisterBase,
[in] ULONGLONG Offset,
[in] ULONG DeviceOffset,
[in, out] PULONG Length,
[in] BOOLEAN WriteToDevice,
[out, optional] PSCATTER_GATHER_LIST ScatterGatherBuffer,
[in] ULONG ScatterGatherBufferLength,
[in, optional] PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
[in, optional] PVOID CompletionContext
)
{...}
參數
[in] DmaAdapter
DMA_ADAPTER 結構的指標。 這個結構是代表驅動程式總線主要 DMA 裝置或系統 DMA 通道的配接器物件。 呼叫端從先前對 ioGetDmaAdapter 例程的呼叫取得此指標。
[in] Mdl
MDL 鏈結的指標，描述虛擬記憶體中鎖定緩衝區集合的實體頁面配置。 DMA 傳輸的散佈/收集清單會使用 Offset 所指定的此記憶體區域，以及 Length 參數。 如需 MDL 鏈結的詳細資訊，請參閱使用 MDL 。
[in] MapRegisterBase
對應緩存器的句柄，配置給配接器物件。 呼叫端先前已從 AllocateAdapterChannelEx 例程取得此句柄。
[in] Offset
MDL 鏈結所描述記憶體開頭的位元組位移。 此位移會指定用於 DMA 傳輸的 I/O 數據緩衝區開頭。 如果散佈/收集清單提供給呼叫端，此位移會決定清單中第一個緩衝區片段的起始位址。 如果 MDL 鏈結中的 MDL 描述記憶體的 N 個字節總計，則 Offset 的有效值介於 0 到 N–1 的範圍內。 如需詳細資訊，請參閱。
[in] DeviceOffset
目標裝置數據快取器或 FIFO 的位元組位移，來自裝置的基位址。 此參數適用於具有可由系統 DMA 控制器存取之多個 FIF 的裝置。 此參數僅用於系統 DMA 傳輸。 針對總線主要傳輸，請將此參數設定為零。
[in, out] Length
變數的指標，其中包含用於 DMA 傳輸之 I/O 數據緩衝區的長度，以位元組為單位。 在專案上，此變數包含呼叫驅動程式所要求的長度。 傳回之前，例程會將對應緩衝區的實際長度寫入這個變數。 從 mapTransferEx 傳回時傳回的 *Length 值， 表示已對應多少個字節。 如果對應緩存器和散佈/收集緩衝區大小數目足以對應呼叫端所要求的整個長度，則 *Length 的輸入和輸出值都相同。 如果 MDL 鏈結中的 MDL 描述記憶體的 N 個字節總數，則有效值為 *Length 的範圍介於 0 到 N–Offset。
[in] WriteToDevice
DMA 傳輸的方向。 將此參數設定為針對寫入作業 TRUE，以從記憶體將數據傳輸到裝置。 將此參數設定為 FALSE 讀取作業，以將數據從裝置傳輸到記憶體。
[out, optional] ScatterGatherBuffer
呼叫端配置的緩衝區指標，例程會將 DMA 傳輸的散佈/收集清單寫入其中。 此清單開頭為 SCATTER_GATHER_LIST 結構，緊接著 SCATTER_GATHER_ELEMENT 陣列。 對於使用總線主要 DMA 裝置的驅動程式，ScatterGatherBuffer 是必要參數。 對於使用系統 DMA 控制器的驅動程式，ScatterGatherBuffer 參數是選擇性的，而且可以 NULL。 如需詳細資訊，請參閱。
[in] ScatterGatherBufferLength
ScatterGatherBuffer 參數指向的緩衝區大小，以位元組為單位。 配置的緩衝區大小必須夠大，才能包含散佈/收集清單，以及作系統在此緩衝區中儲存的內部數據。 若要判斷所需的緩衝區大小，請呼叫 GetDmaTransferInfo 或 CalculateScatterGatherList 例程。 如果 ScatterGatherBufferNULL，請將 ScatterGatherBufferLength 設為零。
[in, optional] DmaCompletionRoutine
呼叫端提供的指標 DmaCompletionRoutine DMA 傳輸完成時呼叫的例程。 如果目標裝置使用產生 DMA 完成中斷的系統 DMA 控制器，就會呼叫此例程。 DmaCompletionRoutine 例程會在 DMA 傳輸完成之後於DISPATCH_LEVEL呼叫。 對於系統 DMA 配接器，這個參數是選擇性的，而且可以 NULL。 針對總線主要配接器，請將此參數設定為 NULL。
[in, optional] CompletionContext
DmaCompletionRoutine 例程的驅動程式決定內容。 此內容會以 CompletionContext 參數的形式提供給 DmaCompletionRoutine 例程。 如果 DmaCompletionRoutine 參數 NULL，請將 CompletionContext 設為 NULL。
傳回值
如果呼叫成功，MapTransferEx 會傳回STATUS_SUCCESS。 可能的錯誤傳回值包括下列狀態代碼。
| 傳回碼 | 描述 |
|---|---|
|
例程失敗，因為呼叫端傳遞的參數值無效。 |
|
ScatterGatherBuffer 中的呼叫端提供的緩衝區 太小，無法包含散佈/收集清單。 |
|
例程無法配置 DMA 傳輸所需的資源。 |
|
此傳輸已取消。 |
言論
MapTransferEx 不是可以直接依名稱呼叫的系統例程。這個例程只能由 DMA_OPERATIONS 結構中傳回之位址的指標呼叫。驅動程式會呼叫 ioGetDmaAdapter ，並將 DeviceDescription 參數的 Version 成員 DEVICE_DESCRIPTION_VERSION3呼叫 IoGetDmaAdapter，以取得此例程的位址。 如果 IoGetDmaAdapter 傳回 NULL ，則您的平台上無法使用例程。
對於使用系統 DMA 控制器的傳輸，呼叫端可以選擇提供 DmaCompletionRoutine 傳輸完成時呼叫的回呼例程。 作系統會排程此回呼，以回應來自系統 DMA 控制器的 DMA 完成中斷。
MapTransferEx 可以設定的地圖緩存器數目不能超過從 ioGetDmaAdapter 從取得的驅動程式上限。
Mdl、Offset和 Length 參數會描述所要求 DMA 傳輸的 I/O 數據緩衝區。 配置之對應緩存器的數目可能不足以對應此緩衝區中的所有記憶體，或是散佈圖/收集緩衝區所指向的 ScatterGatherBuffer 可能不夠大，無法描述整個緩衝區。 MapTransferEx 將輸出值寫入 *Length，以告訴驅動程式例程所對應要求 DMA 傳輸的緩衝區內存數量。 例程會將散佈/收集清單寫入 ScatterGatherBuffer 所指向的緩衝區。 此清單描述例程成功對應的緩衝區片段。
如果呼叫 MapTransferEx 成功，MapTransferEx 會在傳回之前寫入 *Length 輸出值。 如果呼叫端指定 DmaCompletionRoutine，則更新的 *Length 輸出值一律會在 DmaCompletionRoutine 執行之前寫入。 如需詳細資訊，請參閱 MapTransferEx的多個呼叫。
Offset 參數會指定 MDL 鏈結中的起始位移，描述 I/O 數據緩衝區中的記憶體。 例如，假設 MDL 鏈結包含兩個 MDL、MDL₁ 和 MDLー，且 MDL₁ 描述 N₁ 個記憶體位元組，而 MDLー 描述 Nー 位元組。 如果 Offset = N，其中 N₁ < N < N₁ + Nー，則緩衝區不包含 MDL₁ 所描述的記憶體，並且從 N - N₁ 位元組的位移開始。
如果傳輸使用系統 DMA 控制器，則呼叫端可以設定 ScatterGatherBuffer = NULL，在此情況下 MapTransferEx 會使用內部配置的默認緩衝區來保存散佈/收集清單。 默認緩衝區保證夠大，足以包含至少一個元素的散佈/收集清單。 如果默認緩衝區用於散佈/收集傳送許多元素，則可能需要完成傳輸 MapTransferEx 的許多呼叫。 如果 DMA 控制器硬體支援散佈/收集傳輸，則使用預設緩衝區可能會降低效能。
如果 ScatterGatherBuffer 為非 NULL，且 ScatterGatherBufferSize 指定大小太小而無法包含至少一個專案的散佈/收集清單，MapTransferEx 失敗並傳回STATUS_INVALID_PARAMETER。
MapTransferEx 是 mapTransfer 例程的 擴充版本。 擴充版本具有下列優點：
- MapTransferEx 可以在一個呼叫中處理 MDL 鏈結中的所有緩衝區片段，但 MapTransfer 每個呼叫只能處理一個實際連續的緩衝區片段。
- MapTransferEx 可以在一個呼叫中產生整個散佈/收集清單，但 MapTransfer 每個呼叫只能產生一個散佈/收集清單元素。
- MapTransferEx 可以在一次呼叫中對應散佈/收集清單中的所有緩衝區片段，但 MapTransfer 每個呼叫只能對應一個實體連續的緩衝區片段。
- MapTransferEx 只需要整個散佈/收集清單的起始位移，但 MapTransfer 需要每個實體連續緩衝區片段的起始虛擬位址。
- MapTransferEx 呼叫可以對應透過一或多個 MDL 延伸的緩衝區，但是 MapTransfer 呼叫只能對應 MDL 所描述記憶體中一個實際連續的緩衝區片段。
- 針對系統 DMA 傳輸，MapTransferEx 可讓呼叫者提供 DmaCompletionRoutine 回呼例程，以在傳輸完成之後接收通知，但 MapTransfer 不提供在 DMA 傳輸完成時通知呼叫者的方法。
如需詳細資訊，請參閱使用 MapTransferEx 例程 。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | 從 Windows 8 開始提供。 |
| 目標平臺 | 桌面 |
| 標頭 | wdm.h （包括 Wdm.h、Ntddk.h、Ntifs.h） |
| IRQL | <= DISPATCH_LEVEL |