estrutura NET_BUFFER_LIST (ndis/nbl.h)

Artigo
08/07/2023

A estrutura NET_BUFFER_LIST especifica uma lista vinculada de estruturas de NET_BUFFER .

Sintaxe

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;

Membros

Next

O próximo NET_BUFFER_LIST estrutura na cadeia.

Os drivers não devem acessar esse membro diretamente. Em vez disso, eles devem chamar a macro NET_BUFFER_LIST_NEXT_NBL .

FirstNetBuffer

A primeira NET_BUFFER neste NET_BUFFER_LIST.

Os drivers não devem acessar esse membro diretamente. Em vez disso, eles devem chamar a macro NET_BUFFER_LIST_FIRST_NB .

Link

Reservado para NDIS.

NetBufferListHeader

Uma estrutura NET_BUFFER_LIST_HEADER .

Context

Um ponteiro para uma estrutura NET_BUFFER_LIST_CONTEXT . Os drivers de protocolo e miniport usam essa estrutura para armazenar informações sobre a estrutura de NET_BUFFER_LIST. As informações armazenadas na estrutura NET_BUFFER_LIST_CONTEXT são opacas para o NDIS e outros drivers na pilha.

Use as seguintes funções e macros para acessar dados na estrutura NET_BUFFER_LIST_CONTEXT:

NdisAllocateNetBufferListContext NdisFreeNetBufferListContext NET_BUFFER_LIST_CONTEXT_DATA_START NET_BUFFER_LIST_CONTEXT_DATA_SIZE

ParentNetBufferList

Se essa estrutura NET_BUFFER_LIST for um clone de outra estrutura NET_BUFFER_LIST, esse membro especificará um ponteiro para a estrutura de NET_BUFFER_LIST pai. Caso contrário, esse parâmetro será NULL. Um driver usa o Função NdisAllocateCloneNetBufferList para criar um clone.

NdisPoolHandle

Um identificador de pool que identifica o pool de NET_BUFFER_LIST do qual a estrutura de NET_BUFFER_LIST foi alocada.

NdisReserved[2]

Reservado para uso pelo NDIS.

ProtocolReserved[4]

Reservado para uso por drivers de protocolo.

MiniportReserved[2]

Reservado para uso por drivers de miniporta.

Scratch

Dados definidos pelo proprietário atual da estrutura NET_BUFFER_LIST. O proprietário atual, NDIS ou um driver NDIS, pode usar esse membro para suas próprias finalidades. Quando a estrutura NET_BUFFER_LIST é alocada inicialmente, esse membro é NULL. Depois que o proprietário atual abrir mão da propriedade, o NDIS ou outro driver poderá substituir esse membro.

SourceHandle

Um identificador que o NDIS forneceu ao driver em uma operação de associação ou anexação usando uma das seguintes rotinas fornecidas pelo driver:

O NDIS usa SourceHandle para retornar a estrutura NET_BUFFER_LIST para o driver que enviou a estrutura NET_BUFFER_LIST.

NblFlags

Esse membro contém sinalizadores que podem ser combinados com uma operação OR bit a bit.

Use as macros NdisTestNblFlag, NdisTestNblFlags, NdisSetNblFlag e NdisClearNblFlag para acessar os sinalizadores.

Drivers intermediários e drivers de filtro poderão definir os sinalizadores a seguir se não modificarem os dados associados a um NET_BUFFER_LIST. Por exemplo, se os dados não forem alterados, o NDIS poderá reutilizar as informações originais das quais o NET_BUFFER_LIST foi criado.

NDIS_NBL_FLAGS_SEND_READ_ONLY

Se definido, a estrutura NET_BUFFER_LIST e seus dados serão somente leitura para operações de envio.

NDIS_NBL_FLAGS_RECV_READ_ONLY

Se definido, a estrutura NET_BUFFER_LIST e seus dados serão somente leitura para operações de recebimento.

Um driver pode definir os seguintes sinalizadores mesmo que ele não divida o quadro Ethernet associado:

NDIS_NBL_FLAGS_IS_IPV4

Todos os quadros Ethernet nesta estrutura NET_BUFFER_LIST são quadros IPv4. Se esse sinalizador for definido, o provedor de divisão de dados de cabeçalho não deverá definir o sinalizador NDIS_NBL_FLAGS_IS_IPV6.

NDIS_NBL_FLAGS_IS_IPV6

Todos os quadros Ethernet nesta estrutura NET_BUFFER_LIST são quadros IPv6. Se esse sinalizador for definido, o provedor de divisão de dados de cabeçalho não deverá definir o sinalizador NDIS_NBL_FLAGS_IS_IPV4.

NDIS_NBL_FLAGS_IS_TCP

Todos os quadros Ethernet nesta estrutura NET_BUFFER_LIST são quadros TCP. Se esse sinalizador for definido, o provedor de divisão de dados de cabeçalho não deverá definir o sinalizador de NDIS_NBL_FLAGS_IS_UDP e o provedor deverá definir o sinalizador NDIS_NBL_FLAGS_IS_IPV4 ou o sinalizador NDIS_NBL_FLAGS_IS_IPV6.

NDIS_NBL_FLAGS_IS_UDP

Todos os quadros Ethernet nesta estrutura NET_BUFFER_LIST são quadros UDP. Se esse sinalizador for definido, o provedor de divisão de dados de cabeçalho não deverá definir o sinalizador NDIS_NBL_FLAGS_IS_TCP e o provedor deverá definir o sinalizador NDIS_NBL_FLAGS_IS_IPV4 ou o sinalizador de NDIS_NBL_FLAGS_IS_IPV6.

NDIS_NBL_FLAGS_IS_LOOPBACK_PACKET

Todos os pacotes associados a essa estrutura NET_BUFFER_LIST são pacotes de loopback.

Se o provedor de divisão de dados de cabeçalho não dividir o quadro Ethernet associado, o driver de miniporto deverá indicar a estrutura NET_BUFFER_LIST com os seguintes sinalizadores limpos:

NDIS_NBL_FLAGS_HD_SPLIT

O cabeçalho e os dados são divididos em todos os quadros Ethernet associados a essa estrutura NET_BUFFER_LIST.

NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_HEADER

Todos os quadros Ethernet neste NET_BUFFER_LIST são divididos no início do cabeçalho do protocolo de camada superior. Se esse sinalizador for definido, o provedor de divisão de dados de cabeçalho deverá definir o sinalizador NDIS_NBL_FLAGS_IS_IPV4 ou o sinalizador NDIS_NBL_FLAGS_IS_IPV6. Além disso, o provedor pode definir o sinalizador NDIS_NBL_FLAGS_IS_TCP ou o sinalizador NDIS_NBL_FLAGS_IS_UDP, mas o provedor não deve definir o sinalizador NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_PAYLOAD.

NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_PAYLOAD

Todos os quadros Ethernet nesta estrutura NET_BUFFER_LIST são divididos no início do conteúdo TCP ou UDP. Se esse sinalizador for definido, o provedor de divisão de dados de cabeçalho deverá definir o sinalizador NDIS_NBL_FLAGS_IS_IPV4 ou o sinalizador NDIS_NBL_FLAGS_IS_IPV6. Além disso, o provedor deve definir o sinalizador NDIS_NBL_FLAGS_IS_TCP ou o sinalizador NDIS_NBL_FLAGS_IS_UDP, mas o provedor não deve definir o sinalizador NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_HEADER.

ChildRefCount

Se essa estrutura NET_BUFFER_LIST tiver clones (é pai), esse membro especificará o número de clones pendentes. Caso contrário, esse membro será zero.

Flags

Atributos da estrutura NET_BUFFER_LIST. As definições a seguir especificam uma máscara de bits para um conjunto de sinalizadores:

NBL_FLAGS_PROTOCOL_RESERVED

Esse conjunto é reservado para drivers de protocolo.

Nota A partir do NDIS 6.30, dois bits adicionais estão disponíveis para uso de protocolo: 0x00000003. Um protocolo NDIS 6.30 poderá usar esses bits se e somente se NdisGetVersion retornar um valor maior ou igual a NDIS_RUNTIME_VERSION_630. Os protocolos não devem usar esses bits em versões anteriores do NDIS, pois antes da 6.30, o NDIS os usa internamente.

NBL_FLAGS_MINIPORT_RESERVED

Esse conjunto é reservado para drivers de miniporta.

NBL_FLAGS_SCRATCH

O proprietário atual da estrutura NET_BUFFER_LIST, NDIS ou um driver NDIS, pode usar esse conjunto. Quando o proprietário atual renuncia à propriedade, o NDIS ou outro driver pode substituir esses sinalizadores.

NBL_FLAGS_NDIS_RESERVED

Esse conjunto é reservado para NDIS.

Status

A conclusão final status de uma operação de dados de rede nessa estrutura NET_BUFFER_LIST. Os drivers de miniporta gravam esse valor antes de chamar o Função NdisMSendNetBufferListsComplete . Os drivers de miniporto especificam um dos seguintes valores:

NDIS_STATUS_SUCCESS

Todos os dados de rede descritos por NET_BUFFER estruturas associadas a essa estrutura NET_BUFFER_LIST foram transmitidos com êxito pela rede.

NDIS_STATUS_INVALID_LENGTH

O tamanho dos dados em algumas estruturas NET_BUFFER associadas a essa estrutura NET_BUFFER_LIST era muito grande para a NIC subjacente.

NDIS_STATUS_RESOURCES

A solicitação de envio para essa estrutura NET_BUFFER_LIST falhou devido a recursos insuficientes.

NDIS_STATUS_FAILURE

Essa solicitação de envio para essa estrutura de NET_BUFFER_LIST falhou devido a algum motivo diferente daqueles declarados nos três valores anteriores.

NDIS_STATUS_SEND_ABORTED

O NDIS chamou a função MiniportCancelSend para cancelar a operação de envio para essa estrutura NET_BUFFER_LIST.

NDIS_STATUS_RESET_IN_PROGRESS

O driver de miniporte anulou a solicitação de envio devido a uma redefinição.

NDIS_STATUS_PAUSED

Se um driver precisar rejeitar solicitações de envio porque ele está em pausa, ele define o status completo em cada NET_BUFFER_LIST afetado como NDIS_STATUS_PAUSED.

NdisReserved2

Reservado para NDIS.

NetBufferListInfo[MaxNetBufferListInfo]

Uma matriz de valores que contém informações comuns a todas as estruturas NET_BUFFER na lista. Essas informações geralmente são chamadas de "dados OOB (fora de banda)".

Use o NDIS_NET_BUFFER_LIST_INFO valores de enumeração com a macro NET_BUFFER_LIST_INFO para definir e obter valores na matriz NetBufferListInfo .

Comentários

Os drivers NDIS podem chamar qualquer uma das seguintes funções para alocar e inicializar uma estrutura de NET_BUFFER_LIST:

NdisAllocateNetBufferList

NdisAllocateNetBufferAndNetBufferList NdisAllocateCloneNetBufferList NdisAllocateFragmentNetBufferList NdisAllocateReassembledNetBufferList

Todas as estruturas NET_BUFFER associadas a uma estrutura de NET_BUFFER_LIST têm os atributos especificados pelos membros NetBufferListInfo e Context .

Quando um driver chama a função NdisSendNetBufferLists ou NdisFSendNetBufferLists , ele perde a propriedade de:

A estrutura de NET_BUFFER_LIST especificada.
As estruturas NET_BUFFER anexadas e MDLs.
Qualquer NDIS_REQUEST_CONTROLs anexado.
Todos os dados NetBufferListInfo associados à estrutura NET_BUFFER_LIST.

O proprietário atual de uma lista de estruturas de NET_BUFFER_LIST pode mover uma estrutura NET_BUFFER_LIST para outra lista. No entanto, todas as estruturas NET_BUFFER associadas a uma estrutura NET_BUFFER_LIST devem permanecer com a mesma estrutura NET_BUFFER_LIST. Somente o driver que criou as estruturas NET_BUFFER pode movê-las para uma estrutura de NET_BUFFER_LIST diferente. O proprietário atual não pode modificar um membro Next da estrutura NET_BUFFER.

Uma lista de estruturas de NET_BUFFER_LIST é uma lista simples vinculada e terminada por NULL. Para mover uma estrutura de NET_BUFFER_LIST para uma lista diferente, faça as atualizações apropriadas para os membros Next nas listas de origem e destino.

Para acessar membros da estrutura NET_BUFFER_LIST, use as seguintes macros e funções:

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 obter mais informações sobre como usar buffers de rede, consulte Arquitetura de NET_BUFFER.