Share via

Função NdisAllocatePacketPoolEx (ndis.h)

  • Artigo

Nota NDIS 5. x foi preterido e substituído pelo NDIS 6. x. Para obter um novo desenvolvimento de driver NDIS, consulte Drivers de rede começando com o Windows Vista. Para obter informações sobre como portar o NDIS 5. x drivers para NDIS 6. x, consulte Portabilidade de drivers NDIS 5.x para NDIS 6.0.

Essa função aloca e inicializa um bloco de armazenamento para um pool de descritores de pacote.

Sintaxe

void NdisAllocatePacketPoolEx(
  [out] PNDIS_STATUS Status,
  [out] PNDIS_HANDLE PoolHandle,
  [in]  UINT         NumberOfDescriptors,
  [in]  UINT         NumberOfOverflowDescriptors,
  [in]  UINT         ProtocolReservedLength
);

Parâmetros

[out] Status

Aponta para uma variável fornecida pelo chamador na qual essa função retorna o status da alocação do pool de pacotes.

[out] PoolHandle

Aponta para uma variável fornecida pelo chamador na qual essa função retorna um identificador para o pool de pacotes. Esse identificador é um parâmetro necessário para as funções NdisXXXPacket que o driver chama posteriormente.

[in] NumberOfDescriptors

Especifica o número de descritores de pacote que o pool deve conter para uso normal previsto. O máximo de NumberOfDescriptors que podem ser alocados é 0xFFFF. Se for feita uma tentativa de alocar mais do que isso, NdisAllocatePacketPoolEx retornará um Status de NDIS_STATUS_RESOURCES.

[in] NumberOfOverflowDescriptors

Especifica o número de descritores de pacote reservados para uma situação de estouro, ou seja, quando todos os descritores especificados por NumberOfDescriptors estiverem em uso. Se a soma desse parâmetro e NumberOfDescriptors exceder 0xFFFF, NdisAllocatePacketPoolEx reduzirá o valor fornecido como esse parâmetro para que o total de NumberOfDescriptors e NumberOfOverflowDescriptors seja igual a 0xFFFF.

[in] ProtocolReservedLength

Especifica o número de bytes a serem alocados para a matriz ProtocolReserved de cada descritor de pacote. Para descritores de pacote a serem usados em indicações de recebimento, esse parâmetro tem 4*tamanho de (PVOID).

Retornar valor

Nenhum

Comentários

A tabela a seguir mostra os possíveis valores retornados para essa função.

Status Descrição
NDIS_STATUS_SUCCESS O driver pode fazer chamadas para NdisAllocatePacket quando precisa de descritores de pacote para fazer indicações até drivers de nível superior ou para enviar pacotes para drivers de nível inferior.
NDIS_STATUS_RESOURCES A tentativa de alocar o pool de pacotes falhou, possivelmente devido à falta de memória. Esse retorno não significa necessariamente que uma chamada subsequente falhará. No entanto, o chamador pode tentar diminuir os NumberOfDescriptors e chamar novamente imediatamente.

Uma chamada bem-sucedida para NdisAllocatePacketPoolEx retorna um identificador para o pool de pacotes, que o chamador deve salvar. Normalmente, o driver chama NdisAllocatePacket uma ou mais vezes com esse identificador para alocar um conjunto de descritores de pacote.

NdisAllocatePacketPoolEx aloca estaticamente apenas memória suficiente para acomodar o número de descritores de pacote especificados por NumberOfDescriptors. O número total de descritores de pacote que podem ser alocados do pool com chamadas para NdisAllocatePacket é o menor de 0xFFFF ou a soma de NumberOfDescriptors e NumberOfOverflowDescriptors originalmente passados para NdisAllocatePacketPoolEx. Os descritores de estouro são alocados dinamicamente somente durante uma situação de estouro, ou seja, quando os NumberOfDescriptors determinados já foram alocados e ainda estão em uso.

A soma de NumberOfDescriptors e NumberOfOverflowDescriptors é o limite efetivo de quantas vezes o driver pode chamar NdisAllocatePacket antes de chamar NdisFreePacket para retornar um descritor de pacote para a lista gratuita para o pool de pacotes. Quando nenhum descritor de estouro ainda tiver sido alocado, NdisFreePacket retornará o descritor de pacote para o pool alocado estaticamente. Se um ou mais descritores de estouro já tiverem sido alocados, NdisFreePacket retornará o descritor de pacote para a memória do sistema , não para o pool.

O chamador de NdisAllocatePacketPoolEx deve definir NumberOfDescriptors como o número de descritores de pacote necessários para cargas normais previstas. O driver deve definir NumberOfOverflowDescriptors como o número de descritores adicionais necessários para acomodar cargas de pico previstas. Se o número total possível de descritores de pacote (NumberOfDescriptors mais NumberOfOverflowDescriptors) tiver sido alocado do pool, uma chamada para NdisAllocatePacket retornará NDIS_STATUS_RESOURCES.

À medida que os pacotes enviados ou indicados são retornados ao driver de alocação, ele pode reutilizar cada descritor de pacote depois de chamar NdisReinitializePacket e configurá-lo novamente com uma cadeia de descritores de buffer ou o driver pode chamar NdisFreePacket para retornar esse pacote para a lista gratuita. Reinicializar e reutilizar pacotes alocados do pool de pacotes é muito mais rápido do que liberar e, em seguida, ter que realocá-los novamente. Antes que um driver chame NdisReinitializePacket com um descritor de pacote, ele deve salvar os ponteiros em descritores de buffer encadeados ao descritor de pacote, pois NdisReinitializePacket define o cabeçalho da cadeia de buffers como NULL.

Quando um driver não precisa mais de descritores de pacote, ele chama [(nf-ndis-ndisfreepacketpool.md) para liberar o armazenamento alocado com NdisAllocatePacketPoolEx.

Versões do sistema operacional: Windows CE .NET 4.0 e posterior.

Requisitos

Requisito Valor
Cabeçalho ndis.h
Biblioteca Ndis.lib
IRQL IRQL <= DISPATCH_LEVEL

Confira também