NDIS_PD_POST_AND_DRAIN_BUFFER_LIST função de retorno de chamada (ndis.h)

Artigo
02/07/2025

A plataforma PD (PacketDirect) chama a função PDPostAndDrainBufferList de um driver de miniporto compatível com PD para postar estruturas de PD_BUFFER em filas de transmissão/recebimento de PD e esvaziar quaisquer estruturas de PD_BUFFER postadas anteriormente que tenham sido concluídas.

Observação Você deve declarar a função usando o tipo NDIS_PD_POST_AND_DRAIN_BUFFER_LIST. Para obter mais informações, consulte a seção Exemplos a seguir.

Sintaxe

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST NdisPdPostAndDrainBufferList;

VOID() NdisPdPostAndDrainBufferList(
  [in, out] NDIS_PD_QUEUE *Queue,
  [in, out] PD_BUFFER **PostBufferListHead,
  [in, out] PD_BUFFER ***DrainBufferListTail,
  [in]      ULONG MaxDrainCount
)
{...}

Parâmetros

[in, out] Queue

Um ponteiro para a fila de transmissão ou recebimento que receberá buffers postados e terá buffers concluídos removidos.

[in, out] PostBufferListHead

O chefe da lista de postagens. O provedor remove os buffers nesta lista e os adiciona ao Queue.

[in, out] DrainBufferListTail

A parte final da lista de drenos. O provedor remove os buffers concluídos do fila e os adiciona a essa lista.

[in] MaxDrainCount

A quantidade máxima de estruturas PD_BUFFER a serem drenados. O provedor deve garantir que não exceda esse valor. Um conjunto de estruturas de PD_BUFFER parciais que compõem uma única contagem de pacotes L2 é 1.

Valor de retorno

Essa função de retorno de chamada não retorna um valor.

Observações

O provedor remove buffers do PostBufferList e os coloca na fila, começando com o buffer principal na lista e avançando para o próximo buffer até que o PostBufferList esteja vazio ou a fila esteja cheia (ou quase cheia). O provedor avançou para o PostListHead e retorna a nova cabeça de lista para o chamador. O provedor também remove todos os buffers concluídos da fila e os insere na parte final do DrainBufferList e retorna a nova cauda DrainBufferList para o cliente.

Observação O provedor deve esvaziar o máximo de buffers possível para abrir espaço para os buffers que estão sendo postados. O PostBufferList e o DrainBufferList têm a garantia de serem listas de buffers desarticuladas (o cliente nunca fornece o cabeçalho de uma lista de buffers como PostBufferListHead e a parte final da mesma lista que DrainBufferListTail).

O cliente também pode passar uma lista de buffers pós-buffer vazia para apenas esvaziar buffers concluídos sem postar novos buffers. O cliente também pode definir o MaxDrainCount como 0 para apenas postar novos buffers sem esvaziar os buffers concluídos. Em casos raros, o cliente pode invocar a chamada com uma lista de pós-buffer vazia e MaxDrainCount como 0. O provedor não deve assumir o contrário e lidar com essa chamada corretamente, como uma não operação.

exemplos de

Para definir uma função PDPostAndDrainBufferList, primeiro você deve fornecer uma declaração de função que identifique o tipo de função que você está definindo. O Windows fornece um conjunto de tipos de função para drivers. Declarar uma função usando os tipos de função ajuda Análise de Código para Drivers, SDV (Verificador de Driver Estático) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma função PDPostAndDrainBufferList chamada "MyPDPostAndDrainBufferList", use o tipo NDIS_PD_POST_AND_DRAIN_BUFFER_LIST conforme mostrado neste exemplo de código:

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST MyPDPostAndDrainBufferList;

Em seguida, implemente sua função da seguinte maneira:

_Use_decl_annotations_
VOID
 MyPDPostAndDrainBufferList(
    NDIS_PD_QUEUE*  Queue,
    PD_BUFFER**  PostBufferListHead,
    PD_BUFFER*** DrainBufferListTail,
    ULONG  MaxDrainCount
    )
  {...}

O tipo de função NDIS_PD_POST_AND_DRAIN_BUFFER_LIST é definido no arquivo de cabeçalho Ntddndis.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função NDIS_PD_POST_AND_DRAIN_BUFFER_LIST no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers NDIS.

Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

Veja a seguir um snippet de código de exemplo que ilustra os indireções de ponteiro para essa função.

PD_BUFFER* PostHead = NULL;
PD_BUFFER** PostTail = &PostHead;
PD_BUFFER* DrainHead = NULL;
PD_BUFFER** DrainTail = &DrainHead;

PD_BUFFER* bufX = <allocated PD_BUFFER>;

bufX->NextPDBuffer = NULL;
*PostTail = bufX;
PostTail = &bufX->NextPDBuffer;

// BEFORE:
//PostHead == bufX
//PostTail == &bufZ->NextPDBuffer
//DrainHead == NULL
//DrainTail == &DrainHead

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST(
          Queue,
          &PostHead,
          &DrainTail,
          32);

// AFTER:
//PostHead == bufY
//PostTail == &bufZ->NextPDBuffer
//DrainHead == buf1
//DrainTail == &buf5->NextPDBuffer

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 10
servidor com suporte mínimo	Windows Server 2016
da Plataforma de Destino	Windows
cabeçalho	ndis.h
IRQL	<= DISPATCH_LEVEL

Compartilhar via