PROTOCOL_RECEIVE_NET_BUFFER_LISTS funzione di callback (ndis.h)

Articolo
08/07/2023

I processi di funzione ProtocolReceiveNetBufferLists ricevono indicazioni dai driver sottostanti.

Nota È necessario dichiarare la funzione usando il tipo di PROTOCOL_RECEIVE_NET_BUFFER_LISTS . Per altre informazioni, vedere la sezione Esempi seguenti.

Sintassi

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
)
{...}

Parametri

[in] ProtocolBindingContext

Handle in un'area di contesto allocata dal driver del protocollo per mantenere le informazioni sullo stato per un'associazione. Questo handle è stato passato a NDIS in una chiamata precedente alla funzione NdisOpenAdapterEx .

[in] NetBufferLists

Elenco collegato di strutture NET_BUFFER_LIST allocate dal driver sottostante. Ogni struttura NET_BUFFER_LIST è in genere associata a una struttura NET_BUFFER .

[in] PortNumber

Numero di porta che identifica una porta dell'adattatore miniport. Il numero di porta predefinito di una scheda miniport è zero. I driver di protocollo che non usano porte adattatori miniport devono ignorare questo parametro.

[in] NumberOfNetBufferLists

Numero di strutture NET_BUFFER_LIST presenti nell'elenco collegato di strutture in NetBufferLists .

[in] ReceiveFlags

Flag che definiscono gli attributi per l'operazione di invio. I flag possono essere combinati con un'operazione OR. Per cancellare tutti i flag, impostare questo membro su zero. Questa funzione supporta i flag seguenti:

NDIS_RECEIVE_FLAGS_DISPATCH_LEVEL

Specifica che irQL corrente è DISPATCH_LEVEL. Per altre informazioni su questo flag, vedere Dispatch IRQL Tracking.

NDIS_RECEIVE_FLAGS_RESOURCES

Specifica che NDIS recupera la proprietà delle strutture NET_BUFFER_LIST e qualsiasi struttura associata NET_BUFFER immediatamente dopo la chiamata a ProtocolReceiveNetBufferLists restituisce.

NDIS_RECEIVE_FLAGS_SINGLE_ETHER_TYPE

Specifica che tutte le strutture NET_BUFFER_LIST nell'elenco in NetBufferLists hanno lo stesso tipo di protocollo (EtherType).

NDIS_RECEIVE_FLAGS_SINGLE_VLAN

Specifica che tutte le strutture NET_BUFFER_LIST nell'elenco in NetBufferList appartengono alla stessa VLAN.

NDIS_RECEIVE_FLAGS_PERFECT_FILTERED

Specifica che tutte le strutture NET_BUFFER_LIST nell'elenco in NetBufferList includono solo i dati corrispondenti al filtro dei pacchetti e all'elenco multicast assegnati all'adattatore miniport.

NDIS_RECEIVE_FLAGS_SINGLE_QUEUE

Specifica che tutte le strutture NET_BUFFER_LIST nell'elenco in NetBufferList appartengono alla stessa coda di macchine virtuali. Un driver miniport deve impostare questo flag per tutte le indicazioni di ricezione in una coda se il flag di NDIS_RECEIVE_QUEUE_PARAMETERS_PER_QUEUE_RECEIVE_INDICATION è stato impostato nel membro Flags dell'oggetto NDIS_RECEIVE_QUEUE_PARAMETERS struttura quando tale coda è stata allocata.

NDIS_RECEIVE_FLAGS_SHARED_MEMORY_INFO_VALID

Specifica che tutte le strutture NET_BUFFER_LIST nell'elenco in NetBufferList contengono informazioni di memoria condivise valide. Quando questo flag viene impostato su un NET_BUFFER_LIST ricevuto, NDIS considera le informazioni di memoria condivise come valide. Quando questo flag non è impostato, i driver e NDIS ignorano le informazioni sulla memoria condivisa. Ad esempio, i driver intermedi che modificano i dati dei pacchetti possono usare questo flag per determinare se i dati devono essere copiati. I driver miniport possono usare il flag per determinare come liberare la memoria associata a una coda di macchine virtuali quando viene eliminata una coda.

NDIS_RECEIVE_FLAGS_MORE_NBLS

Riservato.

Valore restituito

nessuno

Osservazioni

ProtocolReceiveNetBufferLists è una funzione necessaria per i driver di protocollo. NDIS chiama ProtocolReceiveNetBufferLists dopo che un driver miniport associato chiama il Funzione NdisMIndicateReceiveNetBufferLists . Una chiamata a ProtocolReceiveNetBufferLists può verificarsi anche come risultato di un loopback.

Se il flag NDIS_RECEIVE_FLAGS_RESOURCES nel parametro ReceiveFlags non è impostato, il driver del protocollo mantiene la proprietà delle strutture di NET_BUFFER_LIST finché non chiama l'oggetto Funzione NdisReturnNetBufferLists .

Se NDIS imposta il flag di NDIS_RECEIVE_FLAGS_RESOURCES il driver del protocollo non può conservare la struttura NET_BUFFER_LIST e le risorse associate. Il flag set NDIS_RECEIVE_FLAGS_RESOURCES indica che un driver sottostante è in esecuzione basso sulle risorse di ricezione. In questo caso, la funzione ProtocolReceiveNetBufferLists deve copiare i dati ricevuti nell'archiviazione allocata dal protocollo e restituire il più rapidamente possibile.

Nota Se il flag di NDIS_RECEIVE_FLAGS_RESOURCES è impostato, il driver del protocollo deve conservare il set originale di strutture NET_BUFFER_LIST nell'elenco collegato. Ad esempio, quando questo flag è impostato, il driver potrebbe elaborare le strutture e indicare loro lo stack uno alla volta, ma prima che la funzione restituisca deve ripristinare l'elenco collegato originale.

In un sistema multiprocessore questa funzione può essere eseguita simultaneamente su più processori. Applicare la protezione (ad esempio, usare blocchi di spin) alle strutture di dati critiche accessibili da ProtocolReceiveNetBufferLists.

NDIS chiama ProtocolReceiveNetBufferLists in IRQL<= DISPATCH_LEVEL.

Esempi

Per definire una funzione ProtocolReceiveNetBufferLists , è prima necessario fornire una dichiarazione di funzione che identifica il tipo di funzione che si sta definendo. Windows fornisce un set di tipi di funzione per i driver. La dichiarazione di una funzione usando i tipi di funzione consente l'analisi del codice per i driver, il verifica driver statico (SDV) e altri strumenti di verifica trovano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una funzione ProtocolReceiveNetBufferLists denominata "MyReceiveNetBufferLists ", usare il tipo di PROTOCOL_RECEIVE_NET_BUFFER_LISTS come illustrato in questo esempio di codice:

PROTOCOL_RECEIVE_NET_BUFFER_LISTS MyReceiveNetBufferLists;

Implementare quindi la funzione come indicato di seguito:

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

Il tipo di funzione PROTOCOL_RECEIVE_NET_BUFFER_LISTS è definito nel file di intestazione Ndis.h. Per identificare in modo più accurato gli errori durante l'esecuzione degli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano usate le annotazioni applicate al tipo di funzione PROTOCOL_RECEIVE_NET_BUFFER_LISTS nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver NDIS.

Per informazioni su Use_decl_annotations, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Supportato in NDIS 6.0 e versioni successive.
Piattaforma di destinazione	Windows
Intestazione	ndis.h (includere Ndis.h)
IRQL	<= DISPATCH_LEVEL