NDIS_PD_POST_AND_DRAIN_BUFFER_LIST función de devolución de llamada (ndis.h)

La plataforma PacketDirect (PD) llama a la función PDPostAndDrainBufferList del controlador de miniporte compatible con PD para publicar estructuras de PD_BUFFER en colas de transmisión y recepción de PD y purgar las estructuras de PD_BUFFER publicadas anteriormente que se han completado.

Nota Debe declarar la función mediante el tipo NDIS_PD_POST_AND_DRAIN_BUFFER_LIST . Para obtener más información, consulte la sección Ejemplos siguientes.

 

Sintaxis

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

Puntero a la cola de transmisión o recepción que recibirá búferes publicados y habrá eliminado los búferes completados.

[in, out] PostBufferListHead

Encabezado de la lista de publicaciones. El proveedor quita los búferes de esta lista y los agrega a la cola.

[in, out] DrainBufferListTail

Cola de la lista de purga. El proveedor quita los búferes completados de la cola y los agrega a esta lista.

[in] MaxDrainCount

Cantidad máxima de estructuras de PD_BUFFER que se van a purgar. El proveedor debe asegurarse de que no supere esta cantidad. Un conjunto de estructuras de PD_BUFFER parciales que componen un único recuento de paquetes L2 es 1.

Valor devuelto

Esta función de devolución de llamada no devuelve un valor.

Comentarios

El proveedor quita los búferes de PostBufferList y los coloca en la cola, empezando por el búfer principal de la lista y avanzando al siguiente búfer hasta que PostBufferList esté vacío o la cola esté llena (o casi llena). El proveedor avanza a PostListHead y devuelve el nuevo encabezado de lista al autor de la llamada. El proveedor también quita todos los búferes completados de la cola e los inserta en la cola de DrainBufferList y devuelve la nueva cola DrainBufferList al cliente.

Nota El proveedor debe purgar tantos búferes como pueda para abrir espacio para los búferes que se publican. Se garantiza que PostBufferList y DrainBufferList son listas de búferes no coincides (el cliente nunca proporciona el encabezado de una lista de búferes como PostBufferListHead y la cola de esa misma lista que DrainBufferListTail).

 

El cliente también puede pasar una lista de búferes posteriores vacíos para purgar los búferes completados sin registrar ningún búfer nuevo. El cliente también puede establecer MaxDrainCount en 0 para publicar nuevos búferes sin purgar ningún búfer completado. En raras ocasiones, el cliente puede invocar la llamada con una lista de búferes post vacía y MaxDrainCount en 0. El proveedor no debe asumir lo contrario y controlar dicha llamada correctamente, como una operación sin operación.

Ejemplos

Para definir una función PDPostAndDrainBufferList , primero debe proporcionar una declaración de función que identifique el tipo de función que va a definir. Windows proporciona un conjunto de tipos de función para controladores. Declarar una función mediante los tipos de función ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación a encontrar errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una función PDPostAndDrainBufferList denominada "MyPDPostAndDrainBufferList", use el tipo de NDIS_PD_POST_AND_DRAIN_BUFFER_LIST como se muestra en este ejemplo de código:

NDIS_PD_POST_AND_DRAIN_BUFFER_LIST MyPDPostAndDrainBufferList;

A continuación, implemente la función de la siguiente manera:

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

El tipo de función NDIS_PD_POST_AND_DRAIN_BUFFER_LIST se define en el archivo de encabezado Ntddndis.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función NDIS_PD_POST_AND_DRAIN_BUFFER_LIST en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante tipos de roles de función para controladores NDIS.

Para obtener información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.

A continuación se muestra un fragmento de código de ejemplo que ilustra las direccionamientos indirectos de puntero para esta función.

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	Value
Cliente mínimo compatible	Windows 10
Servidor mínimo compatible	Windows Server 2016
Plataforma de destino	Windows
Encabezado	ndis.h
IRQL	<= DISPATCH_LEVEL