PBUILD_SCATTER_GATHER_LIST回呼函式 (wdm.h)
BuildScatterGatherList 例程會使用驅動程式提供的緩衝區來建置散佈/收集清單，為 DMA 作業準備系統。
語法
PBUILD_SCATTER_GATHER_LIST PbuildScatterGatherList;
NTSTATUS PbuildScatterGatherList(
[in] PDMA_ADAPTER DmaAdapter,
[in] PDEVICE_OBJECT DeviceObject,
[in] PMDL Mdl,
[in] PVOID CurrentVa,
[in] ULONG Length,
[in] PDRIVER_LIST_CONTROL ExecutionRoutine,
[in] PVOID Context,
[in] BOOLEAN WriteToDevice,
[in] PVOID ScatterGatherBuffer,
[in] ULONG ScatterGatherLength
)
{...}
參數
[in] DmaAdapter
IoGetDmaAdapter 所傳回之DMA_ADAPTER結構的指標，代表總線主要適配卡或 DMA 控制器。
[in] DeviceObject
代表 DMA 作業目標裝置之裝置物件的指標。
[in] Mdl
描述目前 IRP 之 MdlAddress 成員所指定之緩衝區的 MDL 指標。
[in] CurrentVa
MDL 中目前虛擬位址的指標，緩衝區要對應至 DMA 傳輸作業。
[in] Length
指定要對應之緩衝區的長度，以位元組為單位。
[in] ExecutionRoutine
驅動程式提供的 AdapterListControl 例程指標，當系統 DMA 控制器或總線主機適配卡可用時，會在 IRQL = DISPATCH_LEVEL呼叫。
[in] Context
呼叫時傳遞至 ExecutionRoutine 之驅動程式判斷內容的指標。
[in] WriteToDevice
表示 DMA 傳輸的方向： TRUE 表示從緩衝區到裝置的傳輸，否則為 FALSE 。
[in] ScatterGatherBuffer
呼叫端提供的緩衝區指標，例程會填入 SCATTER_GATHER_LIST 結構。
[in] ScatterGatherLength
指定 在 ScatterGatherBuffer 參數中傳遞之緩衝區的大小，以位元組為單位。
傳回值
BuildScatterGatherList 會傳回下列其中一個值：
| 傳回碼 | Description |
|---|---|
| STATUS_SUCCESS | 作業已順利完成。 |
| STATUS_INSUFFICIENT_RESOURCES | 系統沒有足夠的地圖緩存器可供傳輸使用。 |
| STATUS_BUFFER_TOO_SMALL | 指定的 Length 太大，無法容納於緩衝區內。 |
備註
BuildScatterGatherList 不是可直接依名稱呼叫的系統例程。 這個例程只能由 DMA_OPERATIONS結構中 傳回之位址的指標呼叫。 驅動程式會呼叫IoGetDmaAdapter，並將DeviceDescription參數的Version成員設定為 DEVICE_DESCRIPTION_VERSION2，以取得此例程的位址。 如果 IoGetDmaAdapter 傳回 NULL，則您的平台上無法使用例程。
BuildScatterGatherList 會執行與 GetScatterGatherList 相同的作業，不同之處在於它會使用 ScatterGatherBuffer 參數中提供的緩衝區來保存所建立的散佈/收集清單。 相反地， GetScatterGatherList 會動態配置緩衝區來保存散佈/收集清單。 如果記憶體不足而無法配置緩衝區， GetScatterGatherList 可能會失敗，並出現STATUS_INSUFFICIENT_RESOURCES錯誤。 必須避免此案例的驅動程式可以預先配置緩衝區來保存散佈/收集清單，並改用 BuildScatterGatherList 。
驅動程式可以使用 CalculateScatterGatherList 例程來判斷要配置以保存散佈/收集清單的緩衝區大小。
驅動程式應該在 ScatterGatherBuffer 中保留散佈/收集清單的指標，以在驅動程式呼叫 PutScatterGatherList 時使用。 驅動程式必須呼叫 PutScatterGatherList (排清清單) ，才能存取清單中的數據。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | 可在 Windows XP 和更新版本的 Windows 中使用。 |
| 目標平台 | 桌面 |
| 標頭 | wdm.h (包含 Wdm.h) |
| IRQL | DISPATCH_LEVEL |
| DDI 合規性規則 | IrqlDispatch (wdm) |