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 al Queue.

[in, out] DrainBufferListTail

Cola de la lista de purga. El proveedor quita los búferes completados de Queue 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.

Observaciones

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 hasta el 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 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 sean listas de búferes no separados (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 los búferes completados. En raras ocasiones, el cliente puede invocar la llamada con una lista de búferes posteriores vacía y MaxDrainCount a 0. El proveedor no debe asumir lo contrario y controlar dicha llamada correctamente, como una operación sin operación.

Ejemplos de

Para definir una función de 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 análisis de código para controladores, comprobador de controladores estáticos (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir un PDPostAndDrainBufferList función denominada "MyPDPostAndDrainBufferList", use el tipo NDIS_PD_POST_AND_DRAIN_BUFFER_LIST tal 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 Declaración de funciones mediante el uso de tipos de roles de función para controladores NDIS.

Para obtener información sobre Use_decl_annotations, vea 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	Valor
cliente mínimo admitido	Windows 10
servidor mínimo admitido	Windows Server 2016
de la plataforma de destino de	Windows
encabezado de	ndis.h
irQL	<= DISPATCH_LEVEL