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

Artículo
08/07/2023

Los procesos de función ProtocolReceiveNetBufferLists reciben indicaciones de los controladores subyacentes.

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

Sintaxis

PROTOCOL_RECEIVE_NET_BUFFER_LISTS ProtocolReceiveNetBufferLists;

void ProtocolReceiveNetBufferLists(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNET_BUFFER_LIST NetBufferLists,
  [in] NDIS_PORT_NUMBER PortNumber,
  [in] ULONG NumberOfNetBufferLists,
  [in] ULONG ReceiveFlags
)
{...}

Parámetros

[in] ProtocolBindingContext

Identificador de un área de contexto que el controlador de protocolo asignó para mantener la información de estado de un enlace. Este identificador se pasó a NDIS en una llamada anterior a la función NdisOpenAdapterEx .

[in] NetBufferLists

Lista vinculada de estructuras de NET_BUFFER_LIST asignadas por el controlador subyacente. Cada estructura NET_BUFFER_LIST normalmente está asociada a una estructura NET_BUFFER .

[in] PortNumber

Número de puerto que identifica un puerto de adaptador de minipuerto. El número de puerto predeterminado de un adaptador de minipuerto es cero. Los controladores de protocolo que no usan puertos de adaptador de minipuerto deben omitir este parámetro.

[in] NumberOfNetBufferLists

Número de estructuras de NET_BUFFER_LIST que se encuentran en la lista vinculada de estructuras en NetBufferLists .

[in] ReceiveFlags

Marcas que definen atributos para la operación de envío. Las marcas se pueden combinar con una operación OR. Para borrar todas las marcas, establezca este miembro en cero. Esta función admite las marcas siguientes:

NDIS_RECEIVE_FLAGS_DISPATCH_LEVEL

Especifica que el IRQL actual está DISPATCH_LEVEL. Para obtener más información sobre esta marca, vea Dispatch IRQL Tracking.

NDIS_RECEIVE_FLAGS_RESOURCES

Especifica que NDIS reclama la propiedad de las estructuras de NET_BUFFER_LIST y las estructuras de NET_BUFFER adjuntas inmediatamente después de la llamada a ProtocolReceiveNetBufferLists devuelve.

NDIS_RECEIVE_FLAGS_SINGLE_ETHER_TYPE

Especifica que todas las estructuras de NET_BUFFER_LIST de la lista de NetBufferLists tienen el mismo tipo de protocolo (EtherType).

NDIS_RECEIVE_FLAGS_SINGLE_VLAN

Especifica que todas las estructuras de NET_BUFFER_LIST de la lista de NetBufferLists pertenecen a la misma VLAN.

NDIS_RECEIVE_FLAGS_PERFECT_FILTERED

Especifica que todas las estructuras de NET_BUFFER_LIST de la lista de NetBufferLists solo incluyen datos que coincidan con el filtro de paquetes y la lista de multidifusión que se asignan al adaptador de miniport.

NDIS_RECEIVE_FLAGS_SINGLE_QUEUE

Especifica que todas las estructuras de NET_BUFFER_LIST de la lista de NetBufferLists pertenecen a la misma cola de máquinas virtuales. Un controlador de minipuerto debe establecer esta marca para todas las indicaciones de recepción en una cola si la marca NDIS_RECEIVE_QUEUE_PARAMETERS_PER_QUEUE_RECEIVE_INDICATION se estableció en el miembro Flags del NDIS_RECEIVE_QUEUE_PARAMETERS estructura cuando se asignó esa cola.

NDIS_RECEIVE_FLAGS_SHARED_MEMORY_INFO_VALID

Especifica que todas las estructuras de NET_BUFFER_LIST de la lista de NetBufferLists contienen información de memoria compartida válida. Cuando esta marca se establece en un NET_BUFFER_LIST recibido, NDIS trata la información de memoria compartida como válida. Cuando no se establece esta marca, los controladores y NDIS omiten la información de memoria compartida. Por ejemplo, los controladores intermedios que modifican los datos de paquetes pueden usar esta marca para determinar si se deben copiar los datos. Los controladores de minipuerto pueden usar la marca para determinar cómo liberar la memoria asociada a una cola de máquina virtual cuando se elimina una cola.

NDIS_RECEIVE_FLAGS_MORE_NBLS

Reservado.

Valor devuelto

None

Observaciones

ProtocolReceiveNetBufferLists es una función necesaria para los controladores de protocolo. NDIS llama a ProtocolReceiveNetBufferLists después de que un controlador de miniporte enlazado llame al Función NdisMIndicateReceiveNetBufferLists . También se puede producir una llamada a ProtocolReceiveNetBufferLists como resultado de un bucle invertido.

Si no se establece la marca NDIS_RECEIVE_FLAGS_RESOURCES en el parámetro ReceiveFlags , el controlador de protocolo conserva la propiedad de las estructuras de NET_BUFFER_LIST hasta que llama a . Función NdisReturnNetBufferLists .

Si NDIS establece el NDIS_RECEIVE_FLAGS_RESOURCES marca el controlador de protocolo no puede conservar la estructura de NET_BUFFER_LIST y los recursos asociados. El conjunto NDIS_RECEIVE_FLAGS_RESOURCES marca indica que un controlador subyacente se está ejecutando poco en los recursos de recepción. En este caso, la función ProtocolReceiveNetBufferLists debe copiar los datos recibidos en el almacenamiento asignado por protocolo y devolver lo más rápido posible.

Nota Si se establece la marca NDIS_RECEIVE_FLAGS_RESOURCES , el controlador de protocolo debe conservar el conjunto original de estructuras de NET_BUFFER_LIST en la lista vinculada. Por ejemplo, cuando se establece esta marca, el controlador podría procesar las estructuras e indicarles la pila de uno en uno, pero antes de que la función devuelva, debe restaurar la lista vinculada original.

En un sistema multiprocesador, esta función se puede ejecutar simultáneamente en más de un procesador. Aplique protección (por ejemplo, use bloqueos de número) a estructuras de datos críticas a las que accede ProtocolReceiveNetBufferLists.

NDIS llama a ProtocolReceiveNetBufferLists en IRQL<= DISPATCH_LEVEL.

Ejemplos

Para definir una función ProtocolReceiveNetBufferLists , 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 ProtocolReceiveNetBufferLists denominada "MyReceiveNetBufferLists", use el tipo de PROTOCOL_RECEIVE_NET_BUFFER_LISTS como se muestra en este ejemplo de código:

PROTOCOL_RECEIVE_NET_BUFFER_LISTS MyReceiveNetBufferLists;

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

_Use_decl_annotations_
VOID
 MyReceiveNetBufferLists(
    NDIS_HANDLE  ProtocolBindingContext,
    PNET_BUFFER_LIST  NetBufferLists,
    NDIS_PORT_NUMBER  PortNumber,
    ULONG  NumberOfNetBufferLists,
    ULONG ReceiveFlags
    )
  {...}

El tipo de función PROTOCOL_RECEIVE_NET_BUFFER_LISTS se define en el archivo de encabezado Ndis.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 PROTOCOL_RECEIVE_NET_BUFFER_LISTS en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, consulte 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, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Se admite en NDIS 6.0 y versiones posteriores.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	<= DISPATCH_LEVEL