NDIS_TCP_OFFLOAD_RECEIVE_INDICATE funzione di callback (ndischimney.h)

Articolo
02/26/2024

[La funzionalità di offload del camino TCP è deprecata e non deve essere usata.]

Una destinazione di offload chiama la funzione NdisTcpOffloadReceiveHandler per indicare che i dati di rete ricevuti sono disponibili per l'utilizzo da parte di un'applicazione client.

Sintassi

NDIS_TCP_OFFLOAD_RECEIVE_INDICATE NdisTcpOffloadReceiveIndicate;

NDIS_STATUS NdisTcpOffloadReceiveIndicate(
  [in]  IN NDIS_HANDLE NdisOffloadHandle,
  [in]  IN PNET_BUFFER_LIST NetBufferList,
  [in]  IN NDIS_STATUS Status,
  [out] OUT PULONG BytesConsumed
)
{...}

Parametri

[in] NdisOffloadHandle

Handle che identifica la connessione TCP offloaded in cui viene effettuata l'indicazione. Quando la connessione è stata scaricata, questo handle è stato fornito nel membro NdisOffloadHandle del NDIS_MINIPORT_OFFLOAD_BLOCK_LIST struttura associata allo stato della connessione.

[in] NetBufferList

Puntatore a una struttura NET_BUFFER_LIST . Ogni struttura NET_BUFFER_LIST descrive un elenco di strutture NET_BUFFER . Ogni struttura NET_BUFFER nell'elenco è mappata a una catena di elenchi di descrittori di memoria (MDL). Gli ELENCHI di dati dati contengono i dati ricevuti. Gli MDL sono bloccati in modo che rimangano residenti, ma non vengono mappati alla memoria di sistema.

La struttura NET_BUFFER_LIST specificata da NetBufferList deve essere una struttura autonoma e non può essere la prima struttura in un elenco collegato di strutture NET_BUFFER_LIST . Le destinazioni di offload possono aggirare questa limitazione concatenando tutti gli MDL necessari alla stessa NET_BUFFER in un'indicazione di ricezione di offload.

[in] Status

La destinazione di offload deve specificare il valore di stato seguente:

NDIS_STATUS_SUCCESS

Ciò indica che lo stack host può mantenere la proprietà delle strutture NET_BUFFER_LIST e delle strutture associate fino a quando non restituisce queste strutture al Funzione MiniportTcpOffloadReceiveReturn della destinazione di offload.

[out] BytesConsumed

Puntatore a una variabile tipizzata ULONG che riceve il numero di byte utilizzati dall'applicazione client.

Valore restituito

La funzione NdisTcpOffloadReceiveHandler può restituire uno dei valori seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	L'applicazione client ha utilizzato tutti i dati di ricezione indicati.
NDIS_STATUS_OFFLOAD_DATA_NOT_ACCEPTED	L'applicazione client ha rifiutato tutti i dati di ricezione indicati.
NDIS_STATUS_OFFLOAD_DATA_PARTIALLY_ACCEPTED	L'applicazione client ha utilizzato un subset dei dati di ricezione indicati. La quantità di dati, in byte, utilizzata dall'applicazione client viene restituita nella variabile specificata dal parametro BytesConsumed .

Commenti

I buffer di ricezione vengono inviati al MiniportTcpOffloadReceive funzione della destinazione di offload. Se le richieste di ricezione assurde (buffer forniti dall'applicazione client) sono disponibili per la connessione, la destinazione di offload deve trasferire i dati di ricezione chiamando Funzione NdisTcpOffloadReceiveComplete . Per altre informazioni, vedere Algoritmo di recapito.

Tutte le richieste di ricezione devono essere completate dalla destinazione di offload (anche se sono richieste di ricezione zero byte).

Dopo che una destinazione di offload ha indicato i dati di ricezione e che i dati sono stati rifiutati, la destinazione di offload non può indicare di nuovo i dati fino a quando lo stack host non pubblica una richiesta di ricezione:

Richieste di ricezione normali
Se lo stack host pubblica le normali richieste di ricezione, la destinazione di offload deve completare queste richieste prima di effettuare eventuali indicazioni di ricezione. Per altre informazioni, vedere Algoritmo di recapito.
Richieste di ricezione zero byte
Lo stack host può pubblicare una richiesta di ricezione a byte zero per abilitare le indicazioni di ricezione dalla destinazione di offload. Una richiesta di ricezione a zero byte è una richiesta in cui il valore del membro DataLength (per altre informazioni, vedere struttura NET_BUFFER ) è zero. Una richiesta di ricezione a byte zero non utilizza dati memorizzati nel buffer.

Durante l'inizializzazione, la destinazione di offload deve allocare due pool di buffer, ognuno dei quali contiene strutture NET_BUFFER_LIST e strutture NET_BUFFER. La destinazione di offload utilizza un pool per ricevere indicazioni attraverso il camino TCP quando si chiama il Funzione NdisTcpOffloadReceiveHandler . La destinazione di offload usa l'altro pool per ricevere indicazioni tramite l'interfaccia NDIS non offload quando si chiama Funzione NdisMIndicateReceiveNetBufferLists .

A ogni struttura NET_BUFFER_LIST allocata deve essere associata una sola struttura NET_BUFFER. Il numero di tali strutture da allocare è fino al writer del driver. Per altre informazioni sull'allocazione di tali strutture, vedere Gestione buffer del driver Miniport.

Purché non stia effettuando un riconoscimento ritardato, la destinazione di offload deve riconoscere i dati ricevuti non appena la destinazione di offload ha buffer interni in cui può depositare i dati. La destinazione di offload può confermare i dati ricevuti prima, durante o dopo aver chiamato la funzione NdisTcpOffloadReceiveHandler .

La destinazione di offload fornisce sempre un valore Status di NDIS_STATUS_SUCCESS quando si chiama la funzione NdisTcpOffloadReceiveHandler . Ciò indica che lo stack host può mantenere la proprietà delle strutture NET_BUFFER_LIST e delle strutture associate fino a quando non restituisce queste strutture alla destinazione di offload.

Se lo stack host restituisce NDIS_STATUS_SUCCESS, a indicare che l'applicazione client ha accettato e utilizzato i dati di ricezione, lo stack host restituirà le strutture NET_BUFFER_LIST all'oggetto Funzione MiniportTcpOffloadReceiveReturn della destinazione di offload. Lo stack host imposterà la variabile specificata dal parametro BytesConsumed sul numero di byte indicati dalla destinazione di offload.
Se lo stack host restituisce NDIS_STATUS_NOT_ACCEPTED, a indicare che l'applicazione client ha rifiutato i dati di ricezione, la destinazione di offload riprende la proprietà delle strutture NET_BUFFER_LIST indicate al ritorno della funzione NdisTcpOffloadReceiveHandler . La destinazione di offload deve memorizzare nel buffer i dati di ricezione in attesa che l'applicazione client post-ricezione buffer sulla connessione. Dopo che l'applicazione client ha ricevuto buffer, la destinazione di offload copia i dati di ricezione memorizzati nel buffer inserito e completa i buffer pubblicati chiamando Funzione NdisTcpOffloadReceiveComplete . Per altre informazioni, vedere Algoritmo di recapito. Lo stack host imposterà la variabile specificata dal parametro BytesConsumed su zero.
Se lo stack host restituisce NDIS_STATUS_OFFLOAD_DATA_PARTIALLY_ACCEPTED, a indicare che l'applicazione client ha utilizzato un subset dei dati di ricezione, la destinazione di offload riprende la proprietà delle strutture NET_BUFFER_LIST indicate quando viene restituita la funzione NdisTcpOffloadReceiveHandler . Lo stack host imposterà la variabile specificata dal parametro BytesConsumed su un valore diverso da zero che specifica la quantità di dati, in byte, utilizzata dall'applicazione client. La destinazione di offload deve memorizzare nel buffer i dati di ricezione rimanenti in previsione che l'applicazione client pubblicherà i buffer di ricezione nella connessione.

Si noti che la destinazione di offload non fornisce mai un valore status di NDIS_STATUS_RESOURCES quando si chiama la funzione NdisTcpOffloadReceiveHandler .

Nel membro RcvIndicationSize della struttura TCP_OFFLOAD_STATE_CACHED, lo stack host può specificare il numero ottimale di byte di dati che la destinazione di offload deve fornire in una singola chiamata alla funzione NdisTcpOffloadReceiveHandler . Per altre informazioni, vedere Uso delle dimensioni dell'indicazione di ricezione specificate.