NdisBuildScatterGatherList function (ndis.h)

Article
10/21/2021

The NdisBuildScatterGatherList function builds a scatter/gather list by using the specified parameters.

Syntax

NDIS_STATUS NdisBuildScatterGatherList(
  [in] IN NDIS_HANDLE                          NdisHandle,
  [in] IN PNDIS_SCATTER_GATHER_LIST_PARAMETERS SGListParameters
);

Parameters

[in] NdisHandle

An NDIS driver or instance handle that was obtained during caller initialization. For example, a miniport driver can use the NDIS handle that it obtained from the NdisMRegisterMiniportDriver or MiniportInitializeEx function. Other NDIS drivers can use the handles from the following functions:

NdisRegisterProtocolDriver

NdisOpenAdapterEx

[in] SGListParameters

A pointer to an NDIS_SCATTER_GATHER_LIST_PARAMETERS structure that specifies the parameters for allocating the scatter/gather list.

Return value

NdisBuildScatterGatherList can return the following status values:

Return code	Description
NDIS_STATUS_SUCCESS	The operation completed successfully.
NDIS_STATUS_BUFFER_TOO_SHORT	The operation failed because the buffer length that is specified in the ScatterGatherListBufferSize member of the NDIS_SCATTER_GATHER_LIST_PARAMETERS structure was too short. In this case, NDIS provided the required buffer size in the ScatterGatherListBufferSizeNeeded member.

Remarks

NDIS drivers call the NdisBuildScatterGatherList function to build a scatter/gather list for a buffer. To call this function, a miniport driver specifies a miniport adapter handle or a protocol driver specifies an NDIS binding handle.

The underlying miniport adapter must have called NdisMRegisterScatterGatherDma before a driver can call NdisBuildScatterGatherList.

NDIS calls the NetProcessSGList function that is specified at the ProcessSGListHandler member of the NDIS_SCATTER_GATHER_LIST_PARAMETERS structure within the context of NdisBuildScatterGatherList.

The drivers must call the NdisFreeScatterGatherList function to free a scatter/gather list that was created with the NdisBuildScatterGatherList function.

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.20 and later.
Target Platform	Universal
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	= DISPATCH_LEVEL