struttura NET_BUFFER_LIST (ndis/nbl.h)

Articolo
08/07/2023

La struttura NET_BUFFER_LIST specifica un elenco collegato di strutture NET_BUFFER .

Sintassi

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;

Members

Next

Struttura NET_BUFFER_LIST successiva nella catena.

I driver non devono accedere direttamente a questo membro. Devono invece chiamare la macro NET_BUFFER_LIST_NEXT_NBL .

FirstNetBuffer

La prima NET_BUFFER in questa NET_BUFFER_LIST.

I driver non devono accedere direttamente a questo membro. Devono invece chiamare la macro NET_BUFFER_LIST_FIRST_NB .

Link

Riservato per NDIS.

NetBufferListHeader

Struttura NET_BUFFER_LIST_HEADER .

Context

Puntatore a una struttura NET_BUFFER_LIST_CONTEXT . I driver protocollo e miniport usano questa struttura per archiviare informazioni sulla struttura NET_BUFFER_LIST. Le informazioni archiviate nella struttura NET_BUFFER_LIST_CONTEXT sono opache per NDIS e altri driver nello stack.

Utilizzare le funzioni e le macro seguenti per accedere ai dati nella struttura NET_BUFFER_LIST_CONTEXT:

NdisAllocateNetBufferListContext NdisFreeNetBufferListContext NET_BUFFER_LIST_CONTEXT_DATA_START NET_BUFFER_LIST_CONTEXT_DATA_SIZE

ParentNetBufferList

Se questa struttura NET_BUFFER_LIST è un clone di un'altra struttura NET_BUFFER_LIST, questo membro specifica un puntatore alla struttura NET_BUFFER_LIST padre. In caso contrario, questo parametro è NULL. Un driver usa il Funzione NdisAllocateCloneNetBufferList per creare un clone.

NdisPoolHandle

Handle del pool che identifica il pool di NET_BUFFER_LIST da cui è stata allocata la struttura NET_BUFFER_LIST.

NdisReserved[2]

Riservato per l'uso da parte di NDIS.

ProtocolReserved[4]

Riservato per l'uso da parte dei driver di protocollo.

MiniportReserved[2]

Riservato per l'uso da parte dei driver miniport.

Scratch

Dati definiti dal proprietario corrente della struttura NET_BUFFER_LIST. Il proprietario corrente, NDIS o un driver NDIS, può usare questo membro a proprio scopo. Quando la struttura NET_BUFFER_LIST viene inizialmente allocata, questo membro è NULL. Dopo che il proprietario corrente rinuncia alla proprietà, NDIS o un altro driver può sovrascrivere questo membro.

SourceHandle

Handle fornito dal NDIS al driver in un'operazione di associazione o di collegamento utilizzando una delle routine fornite dal driver seguenti:

NDIS usa SourceHandle per restituire la struttura NET_BUFFER_LIST al driver che ha inviato la struttura NET_BUFFER_LIST.

NblFlags

Questo membro contiene flag che possono essere combinati con un'operazione OR bit per bit.

Usare le macro NdisTestNblFlag, NdisTestNblFlags, NdisSetNblFlag e NdisClearNblFlag per accedere ai flag.

I driver intermedi e i driver di filtro possono impostare i flag seguenti se non modificano i dati associati a un NET_BUFFER_LIST. Ad esempio, se i dati non sono stati modificati, NDIS potrebbe riutilizzare le informazioni originali da cui è stato creato il NET_BUFFER_LIST.

NDIS_NBL_FLAGS_SEND_READ_ONLY

Se impostato, la struttura NET_BUFFER_LIST e i relativi dati sono di sola lettura per le operazioni di invio.

NDIS_NBL_FLAGS_RECV_READ_ONLY

Se impostato, la struttura NET_BUFFER_LIST e i relativi dati sono di sola lettura per le operazioni di ricezione.

Un driver può impostare i flag seguenti anche se non divide il frame Ethernet associato:

NDIS_NBL_FLAGS_IS_IPV4

Tutti i frame Ethernet in questa struttura NET_BUFFER_LIST sono frame IPv4. Se questo flag è impostato, il provider di suddivisione dei dati di intestazione non deve impostare il flag di NDIS_NBL_FLAGS_IS_IPV6.

NDIS_NBL_FLAGS_IS_IPV6

Tutti i frame Ethernet in questa struttura NET_BUFFER_LIST sono frame IPv6. Se questo flag è impostato, il provider split header-data non deve impostare il flag NDIS_NBL_FLAGS_IS_IPV4.

NDIS_NBL_FLAGS_IS_TCP

Tutti i frame Ethernet in questa struttura NET_BUFFER_LIST sono frame TCP. Se questo flag è impostato, il provider di suddivisione dei dati di intestazione non deve impostare il flag di NDIS_NBL_FLAGS_IS_UDP e il provider deve impostare il flag NDIS_NBL_FLAGS_IS_IPV4 o il flag di NDIS_NBL_FLAGS_IS_IPV6.

NDIS_NBL_FLAGS_IS_UDP

Tutti i frame Ethernet in questa struttura NET_BUFFER_LIST sono frame UDP. Se questo flag è impostato, il provider split header-data non deve impostare il flag di NDIS_NBL_FLAGS_IS_TCP e il provider deve impostare il flag di NDIS_NBL_FLAGS_IS_IPV4 o il flag di NDIS_NBL_FLAGS_IS_IPV6.

NDIS_NBL_FLAGS_IS_LOOPBACK_PACKET

Tutti i pacchetti associati a questa struttura NET_BUFFER_LIST sono pacchetti di loopback.

Se il provider di suddivisione dei dati di intestazione non divide il frame Ethernet associato, il driver miniport deve indicare la struttura NET_BUFFER_LIST con i flag seguenti deselezionati:

NDIS_NBL_FLAGS_HD_SPLIT

L'intestazione e i dati vengono suddivisi in tutti i frame Ethernet associati a questa struttura NET_BUFFER_LIST.

NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_HEADER

Tutti i frame Ethernet in questo NET_BUFFER_LIST vengono suddivisi all'inizio dell'intestazione del protocollo di livello superiore. Se questo flag è impostato, il provider split header-data deve impostare il flag NDIS_NBL_FLAGS_IS_IPV4 o il flag di NDIS_NBL_FLAGS_IS_IPV6. Inoltre, il provider può impostare il flag NDIS_NBL_FLAGS_IS_TCP o il flag di NDIS_NBL_FLAGS_IS_UDP, ma il provider non deve impostare il flag di NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_PAYLOAD.

NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_PAYLOAD

Tutti i frame Ethernet in questa struttura NET_BUFFER_LIST vengono suddivisi all'inizio del payload TCP o UDP. Se questo flag è impostato, il provider split header-data deve impostare il flag NDIS_NBL_FLAGS_IS_IPV4 o il flag di NDIS_NBL_FLAGS_IS_IPV6. Inoltre, il provider deve impostare il flag di NDIS_NBL_FLAGS_IS_TCP o il flag di NDIS_NBL_FLAGS_IS_UDP, ma il provider non deve impostare il flag di NDIS_NBL_FLAGS_SPLIT_AT_UPPER_LAYER_PROTOCOL_HEADER.

ChildRefCount

Se questa struttura NET_BUFFER_LIST ha cloni (è un elemento padre), questo membro specifica il numero di cloni in sospeso. In caso contrario, questo membro è zero.

Flags

Attributi della struttura NET_BUFFER_LIST. Le definizioni seguenti specificano una maschera di bit per un set di flag:

NBL_FLAGS_PROTOCOL_RESERVED

Questo set è riservato per i driver di protocollo.

Nota A partire da NDIS 6.30, sono disponibili due bit aggiuntivi per l'uso del protocollo: 0x00000003. Un protocollo NDIS 6.30 può usare questi bit se e solo se NdisGetVersion restituisce un valore maggiore o uguale a NDIS_RUNTIME_VERSION_630. I protocolli non devono usare questi bit nelle versioni precedenti di NDIS, perché prima della versione 6.30, NDIS li usa internamente.

NBL_FLAGS_MINIPORT_RESERVED

Questo set è riservato per i driver miniport.

NBL_FLAGS_SCRATCH

Il proprietario corrente della struttura NET_BUFFER_LIST, NDIS o un driver NDIS, può usare questo set. Quando il proprietario corrente rinuncia alla proprietà, NDIS o un altro driver può sovrascrivere questi flag.

NBL_FLAGS_NDIS_RESERVED

Questo set è riservato per NDIS.

Status

Stato di completamento finale di un'operazione di dati di rete in questa struttura NET_BUFFER_LIST. I driver Miniport scrivono questo valore prima di chiamare il Funzione NdisMSendNetBufferListsComplete . I driver Miniport specificano uno dei valori seguenti:

NDIS_STATUS_SUCCESS

Tutti i dati di rete descritti da NET_BUFFER strutture associate a questa struttura NET_BUFFER_LIST sono stati trasmessi correttamente in rete.

NDIS_STATUS_INVALID_LENGTH

Le dimensioni dei dati in alcune strutture NET_BUFFER associate a questa struttura NET_BUFFER_LIST erano troppo grandi per la scheda di interfaccia di rete sottostante.

NDIS_STATUS_RESOURCES

La richiesta di invio per questa struttura di NET_BUFFER_LIST non è riuscita a causa di risorse insufficienti.

NDIS_STATUS_FAILURE

Questa richiesta di invio per questa struttura di NET_BUFFER_LIST non è riuscita a causa di un motivo diverso da quelli indicati nei tre valori precedenti.

NDIS_STATUS_SEND_ABORTED

NDIS ha chiamato la funzione MiniportCancelSend per annullare l'operazione di invio per questa struttura NET_BUFFER_LIST.

NDIS_STATUS_RESET_IN_PROGRESS

Il driver miniport ha interrotto la richiesta di invio a causa di una reimpostazione.

NDIS_STATUS_PAUSED

Se un driver deve rifiutare le richieste di invio perché è sospeso, imposta lo stato completo in ogni NET_BUFFER_LIST interessato su NDIS_STATUS_PAUSED.

NdisReserved2

Riservato per NDIS.

NetBufferListInfo[MaxNetBufferListInfo]

Matrice di valori contenente informazioni comuni a tutte le strutture NET_BUFFER nell'elenco. Queste informazioni vengono spesso definite dati fuori banda (OOB).

Usare il NDIS_NET_BUFFER_LIST_INFO valori di enumerazione con la macro NET_BUFFER_LIST_INFO per impostare e ottenere valori nella matrice NetBufferListInfo .

Commenti

I driver NDIS possono chiamare una delle funzioni seguenti per allocare e inizializzare una struttura di NET_BUFFER_LIST:

NdisAllocateNetBufferList

NdisAllocateNetBufferAndNetBufferList NdisAllocateCloneNetBufferList NdisAllocateFragmentNetBufferList NdisAllocateReassembledNetBufferList

Tutte le strutture NET_BUFFER associate a una struttura NET_BUFFER_LIST hanno gli attributi specificati dai membri NetBufferListInfo e Context .

Quando un driver chiama la funzione NdisSendNetBufferLists o NdisFSendNetBufferLists , perde la proprietà di:

Struttura NET_BUFFER_LIST specificata.
Strutture di NET_BUFFER associate e MDL.
Qualsiasi NDIS_REQUEST_CONTROLs collegata.
Tutti i dati NetBufferListInfo associati alla struttura NET_BUFFER_LIST.

Il proprietario corrente di un elenco di strutture NET_BUFFER_LIST può spostare una struttura NET_BUFFER_LIST in un altro elenco. Tuttavia, tutte le strutture NET_BUFFER associate a una struttura NET_BUFFER_LIST devono rimanere con la stessa struttura NET_BUFFER_LIST. Solo il driver che ha creato le strutture NET_BUFFER può spostarle in una struttura di NET_BUFFER_LIST diversa. Il proprietario corrente non può modificare il membro Next di una struttura di NET_BUFFER.

Un elenco di strutture NET_BUFFER_LIST è un semplice elenco collegato e con terminazione NULL. Per spostare una struttura NET_BUFFER_LIST in un elenco diverso, apportare gli aggiornamenti appropriati ai membri Next negli elenchi di origine e di destinazione.

Per accedere ai membri della struttura NET_BUFFER_LIST, utilizzare le macro e le funzioni seguenti:

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

Per altre informazioni sull'uso di net buffer, vedere architettura di NET_BUFFER.