Funzione NdisAllocateNetBufferAndNetBufferList (ndis/nblapi.h)

Articolo
02/07/2025

Chiamare la funzione NdisAllocateNetBufferAndNetBufferList per allocare e inizializzare una struttura NET_BUFFER_LIST inizializzata con una struttura NET_BUFFER preallocata.

Sintassi

NDIS_EXPORTED_ROUTINE NET_BUFFER_LIST * NdisAllocateNetBufferAndNetBufferList(
  [in]           NDIS_HANDLE          PoolHandle,
  [in]           USHORT               ContextSize,
  [in]           USHORT               ContextBackFill,
  [in, optional] __drv_aliasesMem MDL *MdlChain,
  [in]           ULONG                DataOffset,
  [in]           SIZE_T               DataLength
);

Parametri

[in] PoolHandle

Handle del pool di strutture NET_BUFFER_LIST restituito in precedenza da funzione NdisAllocateNetBufferListPool. Il membro fAllocateNetBuffer della struttura NET_BUFFER_LIST_POOL_PARAMETERS passata al chiamante NdisAllocateNetBufferListPool deve essere stato impostato su TRUE e il membro DataSize impostato su zero.

[in] ContextSize

Quantità di utilizzato spazio dati nella struttura NET_BUFFER_LIST_CONTEXT da riservare per il chiamante. L'ContextSize deve essere un multiplo del valore definito da MEMORY_ALLOCATION_ALIGNMENT.

[in] ContextBackFill

Quantità di spazio dati inutilizzato (spazio di riempimento) richiesto dal chiamante. NDIS aggiunge questo valore al ContextSize e alloca spazio aggiuntivo. Il ContextBackFill deve essere un multiplo del valore definito da MEMORY_ALLOCATION_ALIGNMENT.

[in, optional] MdlChain

Puntatore a una catena MDL utilizzata da NDIS per inizializzare la struttura NET_BUFFER preallocata. MdlChain può essere NULL.

[in] DataOffset

Offset iniziale, in byte, dall'inizio del buffer all'inizio del utilizzato spazio dati nella catena MDL. Lo spazio dati prima di questo offset è spazio dati inutilizzato. Pertanto, questo valore rappresenta anche la quantità iniziale di spazio di riempimento disponibile nella catena MDL. Se MdlChain è NULL, DataOffset deve essere 0.

[in] DataLength

Lunghezza, in byte, dell'utilizzato lo spazio dati nella catena MDL. Se MdlChain è NULL, DataLength deve essere 0.

Valore restituito

NdisAllocateNetBufferAndNetBufferList restituisce un puntatore alla struttura NET_BUFFER_LIST allocata. La struttura NET_BUFFER_LIST include una struttura NET_BUFFER. Se l'allocazione non è riuscita, questo puntatore viene NULL.

Osservazioni

Le strutture allocate dalla funzione NdisAllocateNetBufferAndNetBufferList devono provenire da un pool che include strutture NET_BUFFER_LIST associate a strutture NET_BUFFER preallocate. Per creare un pool di questo tipo, è necessario chiamare il funzione NdisAllocateNetBufferListPool con il membro fAllocateNetBuffer della struttura NET_BUFFER_LIST_POOL_PARAMETERS impostata su TRUEe il membro DataSize impostato su zero.

Le struttureNET_BUFFER e NET_BUFFER_LIST note devono essere allocate da un pool di buffer NDIS. Un driver non deve allocare e inizializzare una struttura NET_BUFFER_LIST o NET_BUFFER dal pool di memoria privato o dallo stack.

Chiamare la funzione NdisFreeNetBufferList per liberare una struttura NET_BUFFER_LIST.

La NET_BUFFER preallocata può essere riutilizzata reinizializzandola con un'altra catena MDL quando è proprietaria di NET_BUFFER, ma i campi DataOffset, DataLength, CurrentMdle i campi CurrentMdlOffset nella NET_BUFFER devono essere coerenti con la nuova catena MDL.

Ad esempio, se la catena MDL originale contiene XDataLength e YDataOffsete CurrentMdl inizia con il secondo MDL (M) nella catena MDL originale, CurrentMdlOffset è Z. Il campo MdlChain in NET_BUFFER_DATA deve quindi puntare a una nuova catena MDL contenente X'DataLength e Y'DataOffset. Se CurrentMdl inizia con il terzo MDL (M) nella nuova catena MDL, CurrentMdlOffset è Z'e le macro seguenti devono essere usate per impostare i campi 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';

Fabbisogno

Requisito	Valore
client minimo supportato	Supportato in NDIS 6.0 e versioni successive.
piattaforma di destinazione	Universale
intestazione	ndis/nblapi.h (include ndis.h)
libreria	Ndis.lib
IRQL	<= DISPATCH_LEVEL
regole di conformità DDI	Irql_NetBuffer_Function(ndis), NdisAllocateNetBufferList(ndis), NdisAllocateNetBufferList_InitFail(ndis)