Função NdisAllocateNetBufferAndNetBufferList (ndis/nblapi.h)

Artigo
02/26/2024

Chame a função NdisAllocateNetBufferAndNetBufferList para alocar e inicializar uma estrutura de NET_BUFFER_LIST inicializada com uma estrutura de NET_BUFFER preallocada.

Sintaxe

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
);

Parâmetros

[in] PoolHandle

Um identificador do pool de estruturas NET_BUFFER_LIST que foi retornado anteriormente do Função NdisAllocateNetBufferListPool . O membro fAllocateNetBuffer da estrutura NET_BUFFER_LIST_POOL_PARAMETERS que o chamador passou para NdisAllocateNetBufferListPool deve ter sido definido como TRUE e o membro DataSize definido como zero.

[in] ContextSize

A quantidade de espaço de dados usado na estrutura NET_BUFFER_LIST_CONTEXT a ser reservada para o chamador. O ContextSize deve ser um múltiplo do valor definido por MEMORY_ALLOCATION_ALIGNMENT.

[in] ContextBackFill

A quantidade de espaço de dados não utilizado (espaço de preenchimento invertido) que o chamador requer. O NDIS adiciona esse valor ao ContextSize e aloca espaço adicional. O ContextBackFill deve ser um múltiplo do valor definido por MEMORY_ALLOCATION_ALIGNMENT.

[in, optional] MdlChain

Um ponteiro para uma cadeia de MDL que o NDIS usa para inicializar a estrutura de NET_BUFFER pré-alocada. MdlChain pode ser NULL.

[in] DataOffset

O deslocamento inicial, em bytes, desde o início do buffer até o início do espaço de dados usado na cadeia de MDL. O espaço de dados antes desse deslocamento é espaço de dados não utilizado. Portanto, esse valor também representa a quantidade inicial de espaço de backfill disponível na cadeia de MDL. Se MdlChain for NULL, DataOffset deverá ser 0.

[in] DataLength

O comprimento, em bytes, do espaço de dados usado na cadeia de MDL. Se MdlChain for NULL, DataLength deverá ser 0.

Retornar valor

NdisAllocateNetBufferAndNetBufferList retorna um ponteiro para a estrutura de NET_BUFFER_LIST alocada. A estrutura NET_BUFFER_LIST inclui uma estrutura NET_BUFFER. Se a alocação não tiver sido bem-sucedida, esse ponteiro será NULL.

Comentários

As estruturas alocadas pela função NdisAllocateNetBufferAndNetBufferList devem vir de um pool que inclua estruturas de NET_BUFFER_LIST emparelhadas com estruturas de NET_BUFFER preallocadas. Para criar esse pool, você deve chamar o A função NdisAllocateNetBufferListPool com o membro fAllocateNetBuffer da estrutura NET_BUFFER_LIST_POOL_PARAMETERS definida como TRUE e o membro DataSize definido como zero.

ObserveNET_BUFFER e estruturas de NET_BUFFER_LIST devem ser alocadas de um pool de buffers NDIS. Um driver não deve alocar e inicializar uma estrutura NET_BUFFER_LIST ou NET_BUFFER de seu pool de memória privada ou da pilha.

Chame a função NdisFreeNetBufferList para liberar uma estrutura NET_BUFFER_LIST .

A NET_BUFFER preallocada pode ser reutilizada reinicializando-a com outra cadeia de MDL quando possui NET_BUFFER, mas os campos DataOffset, DataLength, CurrentMdl e CurrentMdlOffset no NET_BUFFER devem ser consistentes com a nova cadeia de MDL.

Por exemplo, se a cadeia de MDL original contiver XDataLength e YDataOffset, e CurrentMdl começar com o segundo MDL (M) na cadeia MDL original, CurrentMdlOffset será Z. O campo MdlChain no NET_BUFFER_DATA então precisa apontar para uma nova cadeia de MDL que contém X'DataLength e Y'DataOffset. Se CurrentMdl começar com o terceiro MDL (M') na nova cadeia de MDL, CurrentMdlOffset será Z' e as seguintes macros precisarão ser usadas para definir campos em 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';

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Com suporte no NDIS 6.0 e posterior.
Plataforma de Destino	Universal
Cabeçalho	ndis/nblapi.h (inclua ndis.h)
Biblioteca	Ndis.lib
IRQL	<= DISPATCH_LEVEL
Regras de conformidade de DDI	Irql_NetBuffer_Function(ndis), NdisAllocateNetBufferList(ndis), NdisAllocateNetBufferList_InitFail(ndis)