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

A plataforma PacketDirect (PD) 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 as estruturas de PD_BUFFER postadas anteriormente que foram concluídas.

Nota 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 cabeçalho da lista de postagens. O provedor remove os buffers nesta lista e os adiciona à Fila.

[in, out] DrainBufferListTail

A parte final da lista de dreno. O provedor remove todos os buffers concluídos da Fila e os adiciona a essa lista.

[in] MaxDrainCount

A quantidade máxima de PD_BUFFER estruturas 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.

Retornar valor

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

Comentários

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 PostBufferList esteja vazio ou a fila esteja cheia (ou quase cheia). O provedor avançou para o PostListHead e retorna o cabeçalho da nova 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.

Nota O provedor deve esvaziar o máximo de buffers que puder 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 dessa mesma lista que DrainBufferListTail).

 

O cliente também pode passar uma lista de pós-buffer vazia para apenas esvaziar buffers concluídos sem postar nenhum novo buffer. O cliente também pode definir MaxDrainCount como 0 para apenas postar novos buffers sem esvaziar 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

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 a 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
Cliente mínimo com suporte	Windows 10
Servidor mínimo com suporte	Windows Server 2016
Plataforma de Destino	Windows
Cabeçalho	ndis.h
IRQL	<= DISPATCH_LEVEL