Compartilhar via

Função NdisAllocatePacketPoolEx (ndis.h)

  • Artigo

Observação 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 o 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 o NdisXXXPacket funções 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 este parâmetro para que o total 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*tamanhos de (PVOID).

Valor de retorno

Nenhum

Observações

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

Estado 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 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 o NumberOfDescriptors e ligar 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 passado originalmente para NdisAllocatePacketPoolEx. Os descritores de estouro são alocados dinamicamente somente durante uma situação de estouro, ou seja, quando os NumberOfDescriptors 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 pacotes 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 para o número de descritores de pacote necessários para cargas normais previstas. O driver deve definir NumberOfOverflowDescriptors para o número de descritores adicionais necessários para acomodar as 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.

Como 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 à 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 para os descritores de buffer encadeados ao descritor de pacote, pois NdisReinitializePacket define o cabeçalho da cadeia de buffer 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

Consulte também