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
指向描述由 MdlAddress 当前 IRP 成员指定的缓冲区的 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 返回以下值之一：
| 返回代码 | 描述 |
|---|---|
| STATUS_SUCCESS | 作已成功完成。 |
| STATUS_INSUFFICIENT_RESOURCES | 系统没有足够的映射寄存器可用于传输。 |
| STATUS_BUFFER_TOO_SMALL | 指定的 长度 太大，无法容纳在缓冲区中。 |
言论
BuildScatterGatherList 不是可以直接按名称调用的系统例程。 只能通过从 DMA_OPERATIONS 结构中返回的地址的指针调用此例程。 驱动程序通过调用 IoGetDmaAdapter，并将 DeviceDescription 参数 版本 成员设置为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） |