NET_BUFFER_LIST estructura (ndis/nbl.h)

Artículo
08/07/2023

La estructura NET_BUFFER_LIST especifica una lista vinculada de estructuras de NET_BUFFER .

Sintaxis

typedef struct _NET_BUFFER_LIST {
  union {
    struct {
      NET_BUFFER_LIST *Next;
      NET_BUFFER      *FirstNetBuffer;
    };
    SLIST_HEADER           Link;
    NET_BUFFER_LIST_HEADER NetBufferListHeader;
  };
  NET_BUFFER_LIST_CONTEXT *Context;
  NET_BUFFER_LIST         *ParentNetBufferList;
  NDIS_HANDLE             NdisPoolHandle;
  PVOID                   NdisReserved[2];
  PVOID                   ProtocolReserved[4];
  PVOID                   MiniportReserved[2];
  PVOID                   Scratch;
  NDIS_HANDLE             SourceHandle;
  ULONG                   NblFlags;
  LONG                    ChildRefCount;
  ULONG                   Flags;
  union {
    NDIS_STATUS Status;
    ULONG       NdisReserved2;
  };
  PVOID                   NetBufferListInfo[MaxNetBufferListInfo];
} NET_BUFFER_LIST, *PNET_BUFFER_LIST;

Miembros

Next

La siguiente estructura NET_BUFFER_LIST en la cadena.

Los controladores no deben acceder directamente a este miembro. En su lugar, deben llamar a la macro NET_BUFFER_LIST_NEXT_NBL .

FirstNetBuffer

La primera NET_BUFFER en esta NET_BUFFER_LIST.

Los controladores no deben acceder directamente a este miembro. En su lugar, deben llamar a la macro NET_BUFFER_LIST_FIRST_NB .

Link

Reservado para NDIS.

NetBufferListHeader

Estructura NET_BUFFER_LIST_HEADER .

Context

Puntero a una estructura de NET_BUFFER_LIST_CONTEXT . Los controladores de protocolo y minipuerto usan esta estructura para almacenar información sobre la estructura de NET_BUFFER_LIST. La información almacenada en la estructura de NET_BUFFER_LIST_CONTEXT es opaca para NDIS y otros controladores de la pila.

Use las siguientes funciones y macros para acceder a los datos de la estructura NET_BUFFER_LIST_CONTEXT:

NdisAllocateNetBufferListContext NdisFreeNetBufferListContext NET_BUFFER_LIST_CONTEXT_DATA_START NET_BUFFER_LIST_CONTEXT_DATA_SIZE

ParentNetBufferList

Si esta estructura de NET_BUFFER_LIST es un clon de otra estructura de NET_BUFFER_LIST, este miembro especifica un puntero a la estructura NET_BUFFER_LIST primaria. De lo contrario, este parámetro es NULL. Un controlador usa el Función NdisAllocateCloneNetBufferList para crear un clon.

NdisPoolHandle

Identificador de grupo que identifica el grupo de NET_BUFFER_LIST del que se asignó la estructura de NET_BUFFER_LIST.

NdisReserved[2]

Reservado para su uso por NDIS.

ProtocolReserved[4]

Reservado para su uso por controladores de protocolo.

MiniportReserved[2]

Reservado para su uso por los controladores de minipuerto.

Scratch

Datos definidos por el propietario actual de la estructura NET_BUFFER_LIST. El propietario actual, ya sea NDIS o un controlador NDIS, puede usar este miembro para sus propios fines. Cuando se asigna inicialmente la estructura NET_BUFFER_LIST, este miembro es NULL. Una vez que el propietario actual renuncia a la propiedad, NDIS u otro controlador puede sobrescribir este miembro.

SourceHandle

Identificador que NDIS proporcionó al controlador en una operación de enlace o conexión mediante una de las siguientes rutinas proporcionadas por el controlador:

NDIS usa SourceHandle para devolver la estructura de NET_BUFFER_LIST al controlador que envió la estructura NET_BUFFER_LIST.

NblFlags

Este miembro contiene marcas que se pueden combinar con una operación OR bit a bit.

Use las macros NdisTestNblFlag, NdisTestNblFlags, NdisSetNblFlag y NdisClearNblFlag para acceder a las marcas.

Los controladores intermedios y los controladores de filtro pueden establecer las marcas siguientes si no modifican los datos asociados a un NET_BUFFER_LIST. Por ejemplo, si los datos no cambiaron, NDIS podría reutilizar la información original a partir de la cual se creó el NET_BUFFER_LIST.

NDIS_NBL_FLAGS_SEND_READ_ONLY

Si se establece, la estructura de NET_BUFFER_LIST y sus datos son de solo lectura para las operaciones de envío.

NDIS_NBL_FLAGS_RECV_READ_ONLY

Si se establece, la estructura de NET_BUFFER_LIST y sus datos son de solo lectura para las operaciones de recepción.

Un controlador puede establecer las marcas siguientes aunque no divida el marco Ethernet asociado:

NDIS_NBL_FLAGS_IS_IPV4

Todos los marcos Ethernet de esta estructura NET_BUFFER_LIST son marcos IPv4. Si se establece esta marca, el proveedor de división de datos de encabezado no debe establecer la marca de NDIS_NBL_FLAGS_IS_IPV6.

NDIS_NBL_FLAGS_IS_IPV6

Todos los marcos Ethernet de esta estructura NET_BUFFER_LIST son marcos IPv6. Si se establece esta marca, el proveedor de división de datos de encabezado no debe establecer la marca NDIS_NBL_FLAGS_IS_IPV4.

NDIS_NBL_FLAGS_IS_TCP

Todos los marcos Ethernet de esta estructura NET_BUFFER_LIST son marcos TCP. Si se establece esta marca, el proveedor de división de datos de encabezado no debe establecer la marca de NDIS_NBL_FLAGS_IS_UDP y el proveedor debe establecer la marca NDIS_NBL_FLAGS_IS_IPV4 o la marca NDIS_NBL_FLAGS_IS_IPV6.

NDIS_NBL_FLAGS_IS_UDP

Todos los marcos Ethernet de esta estructura NET_BUFFER_LIST son marcos UDP. Si se establece esta marca, el proveedor de división de datos de encabezado no debe establecer la marca de NDIS_NBL_FLAGS_IS_TCP y el proveedor debe establecer la marca NDIS_NBL_FLAGS_IS_IPV4 o la marca de NDIS_NBL_FLAGS_IS_IPV6.

NDIS_NBL_FLAGS_IS_LOOPBACK_PACKET

Todos los paquetes asociados a esta estructura de NET_BUFFER_LIST son paquetes de bucle invertido.

Si el proveedor de división de datos de encabezado no divide el marco Ethernet asociado, el controlador de miniporte debe indicar la estructura de NET_BUFFER_LIST con las marcas siguientes desactivadas:

NDIS_NBL_FLAGS_HD_SPLIT

El encabezado y los datos se dividen en todos los marcos Ethernet asociados a esta estructura de NET_BUFFER_LIST.

NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_HEADER

Todos los marcos Ethernet de este NET_BUFFER_LIST se dividen al principio del encabezado del protocolo de capa superior. Si se establece esta marca, el proveedor de división de datos de encabezado debe establecer la marca NDIS_NBL_FLAGS_IS_IPV4 o la marca NDIS_NBL_FLAGS_IS_IPV6. Además, el proveedor puede establecer la marca NDIS_NBL_FLAGS_IS_TCP o la marca de NDIS_NBL_FLAGS_IS_UDP, pero el proveedor no debe establecer la marca de NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_PAYLOAD.

NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_PAYLOAD

Todos los marcos Ethernet de esta estructura de NET_BUFFER_LIST se dividen al principio de la carga TCP o UDP. Si se establece esta marca, el proveedor de división de datos de encabezado debe establecer la marca NDIS_NBL_FLAGS_IS_IPV4 o la marca NDIS_NBL_FLAGS_IS_IPV6. Además, el proveedor debe establecer la marca NDIS_NBL_FLAGS_IS_TCP o la marca NDIS_NBL_FLAGS_IS_UDP, pero el proveedor no debe establecer la marca de NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_HEADER.

ChildRefCount

Si esta estructura de NET_BUFFER_LIST tiene clones (es un elemento primario), este miembro especifica el número de clones pendientes. De lo contrario, este miembro es cero.

Flags

Atributos de la estructura NET_BUFFER_LIST. Las definiciones siguientes especifican una máscara de bits para un conjunto de marcas:

NBL_FLAGS_PROTOCOL_RESERVED

Este conjunto está reservado para controladores de protocolo.

Nota A partir de NDIS 6.30, hay dos bits adicionales disponibles para el uso del protocolo: 0x00000003. Un protocolo NDIS 6.30 puede usar estos bits si y solo si NdisGetVersion devuelve un valor mayor o igual que NDIS_RUNTIME_VERSION_630. Los protocolos no deben usar estos bits en versiones anteriores de NDIS, ya que antes de la versión 6.30, NDIS los usa internamente.

NBL_FLAGS_MINIPORT_RESERVED

Este conjunto está reservado para los controladores de minipuerto.

NBL_FLAGS_SCRATCH

El propietario actual de la estructura NET_BUFFER_LIST, ya sea NDIS o un controlador NDIS, puede usar este conjunto. Cuando el propietario actual renuncia a la propiedad, NDIS u otro controlador pueden sobrescribir estas marcas.

NBL_FLAGS_NDIS_RESERVED

Este conjunto está reservado para NDIS.

Status

Estado final de finalización de una operación de datos de red en esta estructura de NET_BUFFER_LIST. Los controladores de minipuerto escriben este valor antes de llamar a Función NdisMSendNetBufferListsComplete . Los controladores de minipuerto especifican uno de los siguientes valores:

NDIS_STATUS_SUCCESS

Todos los datos de red descritos por NET_BUFFER estructuras asociadas a esta estructura de NET_BUFFER_LIST se transmitieron correctamente a través de la red.

NDIS_STATUS_INVALID_LENGTH

El tamaño de los datos de algunas estructuras de NET_BUFFER asociadas a esta estructura de NET_BUFFER_LIST era demasiado grande para la NIC subyacente.

NDIS_STATUS_RESOURCES

Error en la solicitud de envío para esta estructura de NET_BUFFER_LIST debido a recursos insuficientes.

NDIS_STATUS_FAILURE

No se pudo realizar esta solicitud de envío para esta estructura de NET_BUFFER_LIST debido a algún motivo distinto de los indicados en los tres valores anteriores.

NDIS_STATUS_SEND_ABORTED

NDIS llamó a la función MiniportCancelSend para cancelar la operación de envío de esta estructura NET_BUFFER_LIST.

NDIS_STATUS_RESET_IN_PROGRESS

El controlador de minipuerto anuló la solicitud de envío debido a un restablecimiento.

NDIS_STATUS_PAUSED

Si un controlador debe rechazar las solicitudes de envío porque está en pausa, establece el estado completo en cada NET_BUFFER_LIST afectado en NDIS_STATUS_PAUSED.

NdisReserved2

Reservado para NDIS.

NetBufferListInfo[MaxNetBufferListInfo]

Matriz de valores que contiene información común a todas las estructuras NET_BUFFER de la lista. Esta información se conoce a menudo como "datos fuera de banda (OOB).

Use el NDIS_NET_BUFFER_LIST_INFO valores de enumeración con la macro NET_BUFFER_LIST_INFO para establecer y obtener valores en la matriz NetBufferListInfo .

Comentarios

Los controladores NDIS pueden llamar a cualquiera de las funciones siguientes para asignar e inicializar una estructura de NET_BUFFER_LIST:

NdisAllocateNetBufferList

NdisAllocateNetBufferAndNetBufferList NdisAllocateCloneNetBufferList NdisAllocateFragmentNetBufferList NdisAllocateReassembledNetBufferList

Todas las estructuras NET_BUFFER asociadas a una estructura de NET_BUFFER_LIST tienen los atributos especificados por los miembros NetBufferListInfo y Context .

Cuando un controlador llama a la función NdisSendNetBufferLists o NdisFSendNetBufferLists , pierde la propiedad de:

Estructura NET_BUFFER_LIST especificada.
Estructuras y MDL de NET_BUFFER adjuntas.
Cualquier NDIS_REQUEST_CONTROLs adjunta.
Todos los datos de NetBufferListInfo asociados a la estructura NET_BUFFER_LIST.

El propietario actual de una lista de estructuras de NET_BUFFER_LIST puede mover una estructura de NET_BUFFER_LIST a otra lista. Sin embargo, todas las estructuras de NET_BUFFER asociadas a una estructura de NET_BUFFER_LIST deben permanecer con la misma estructura de NET_BUFFER_LIST. Solo el controlador que creó las estructuras de NET_BUFFER puede moverlas a una estructura de NET_BUFFER_LIST diferente. El propietario actual no puede modificar el miembro Next de una estructura NET_BUFFER.

Una lista de estructuras de NET_BUFFER_LIST es una lista sencilla vinculada y terminada en NULL. Para mover una estructura de NET_BUFFER_LIST a otra lista, realice las actualizaciones adecuadas para los miembros Next en las listas de origen y destino.

Para acceder a los miembros de la estructura de NET_BUFFER_LIST, use las siguientes macros y funciones:

NET_BUFFER_LIST_NEXT_NBL

NET_BUFFER_LIST_FIRST_NB

NET_BUFFER_LIST_FLAGS

NET_BUFFER_LIST_MINIPORT_RESERVED NET_BUFFER_LIST_CONTEXT_DATA_START NET_BUFFER_LIST_CONTEXT_DATA_SIZE

NET_BUFFER_LIST_INFO

NET_BUFFER_LIST_STATUS

NET_BUFFER_LIST_PROTOCOL_RESERVED NdisGetPoolFromNetBufferList

Para obtener más información sobre cómo usar búferes netos, consulte arquitectura de NET_BUFFER.