NdisAllocateNetBufferAndNetBufferList (Compact 2013)

  • [アーティクル]

3/26/2014

Call this function to allocate and initialize a NET_BUFFER_LIST structure that is initialized with a preallocated NET_BUFFER structure.

Syntax

PNET_BUFFER_LIST
  NdisAllocateNetBufferAndNetBufferList (
    IN NDIS_HANDLE  PoolHandle,
    IN USHORT  ContextSize,
    IN USHORT  ContextBackFill,
    IN PMDL  MdlChain,
    IN ULONG  DataOffset,
    IN SIZE_T  DataLength
    );

Parameters

  • PoolHandle
    A NET_BUFFER_LIST structure pool handle that was previously returned from the NdisAllocateNetBufferListPool function. The fAllocateNetBuffer member of the NET_BUFFER_LIST_POOL_PARAMETERS structure that the caller passed to NdisAllocateNetBufferListPool must have been set to TRUE and the DataSize member set to zero.
  • ContextSize
    The used data space in the NET_BUFFER_LIST_CONTEXT structure to reserve for the caller. The ContextSize must be a multiple of the value that is defined by MEMORY_ALLOCATION_ALIGNMENT.
  • ContextBackFill
    The unused data space (backfill space) that the caller requires. NDIS adds this value to the ContextSize and allocates additional space. The ContextBackFill must be a multiple of the value that is defined by MEMORY_ALLOCATION_ALIGNMENT.
  • MdlChain
    A pointer to an MDL chain that NDIS uses to initialize the preallocated NET_BUFFER structure. MdlChain can be NULL.
  • DataOffset
    The initial offset, in bytes, from the start of the buffer to the start of the used dataspace in the MDL chain. Dataspace ahead of this offset is unused data space. Therefore, this value also represents the initial amount of available backfill space in the MDL chain. If MdlChain is NULL, DataOffset must be 0.
  • DataLength
    The length, in bytes, of the used data space in the MDL chain. If MdlChain is NULL, DataLength must be 0.

Return Value

NdisAllocateNetBufferAndNetBufferList returns a pointer to the allocated NET_BUFFER_LIST structure. The NET_BUFFER_LIST structure includes a NET_BUFFER structure. If the allocation was unsuccessful, this pointer is NULL.

Remarks

The structures that the NdisAllocateNetBufferAndNetBufferList function allocates must come from a pool that includes NET_BUFFER_LIST structures that are paired with preallocated NET_BUFFER structures. To create such a pool, you must call the NdisAllocateNetBufferListPool function that uses the fAllocateNetBuffer member of the NET_BUFFER_LIST_POOL_PARAMETERS structure set to TRUE, and the DataSize member set to zero.

Call the NdisFreeNetBufferList function to free a NET_BUFFER_LIST structure.

The preallocated NET_BUFFER can be reused by reinitializing it with another MDL chain when it owns NET_BUFFER, but the DataOffset, DataLength, CurrentMdl, and CurrentMdlOffset fields in the NET_BUFFER must be consistent with the new MDL chain.

For example, if the original MDL chain contains X DataLength and Y DataOffset, and CurrentMdl starts with the second MDL (say M) in the original MDL chain, CurrentMdlOffset is Z. The MdlChainfield in NET_BUFFER_DATA then has to point to a new MDL chain that contains X' DataLength and Y' DataOffset. If CurrentMdl starts with the third MDL (say M') in the new MDL chain, CurrentMdlOffset is Z' and the following macros must be used to set fields in NET_BUFFER:

NET_BUFFER_FIRST_MDL(_NB) = New MDL chain;
NET_BUFFER_DATA_LENGTH(_NB) = X';
NET_BUFFER_DATA_OFFSET(_NB) = Y';
NET_BUFFER_CURRENT_MDL(_NB) = M';
NET_BUFFER_CURRENT_MDL_OFFSET(_NB) = Z';

Requirements

Header

ndis.h

See Also

Reference

NDIS NET_BUFFER Functions
NdisAllocateNetBufferListPool
NdisFreeNetBufferList
NET_BUFFER
NET_BUFFER_LIST
NET_BUFFER_LIST_CONTEXT