NDIS_TCP_OFFLOAD_RECEIVE_INDICATE funzione di callback (ndischimney.h)

Articolo
02/07/2025

[La funzionalità 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 NdisOffloadHandle membro 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 viene mappata a una catena di elenchi di descrittori di memoria (MDLs). Gli mdls contengono i dati ricevuti. Gli mdls 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 il numero di MDL necessario allo stesso NET_BUFFER in un'indicazione di ricezione offload.

[in] Status

La destinazione di offload deve fornire 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 all'oggetto 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.

Osservazioni

I buffer di ricezione vengono inseriti nell'oggetto funzione miniportTcpOffloadReceive 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 di zero byte).

Dopo che una destinazione di offload ha indicato di ricevere dati e che i dati sono stati rifiutati, la destinazione di offload non può indicare di nuovo i dati finché lo stack host non invia una richiesta di ricezione:

Richieste di ricezione normali
Se lo stack host invia richieste di ricezione normali, 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 a byte zero
Lo stack host può registrare una richiesta di ricezione a zero byte per abilitare le indicazioni di ricezione dalla destinazione di offload. Una richiesta di ricezione a zero byte è una in cui il valore del membro datalength (per altre informazioni, vedere struttura NET_BUFFER) è zero. Una richiesta di ricezione a zero byte 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 Miniport Driver Buffer Management.

Purché non stia effettuando un riconoscimento ritardato, la destinazione di offload deve confermare 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 NdisTcpOffloadOffloadReceiveHandler. 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 imposta 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 previsione che l'applicazione client posticherà buffer di ricezione sulla connessione. Dopo la ricezione dei buffer da parte dell'applicazione client, la destinazione di offload copia i dati di ricezione memorizzati nei buffer inseriti e completa i buffer pubblicati chiamando funzione NdisTcpOffloadReceiveComplete. Per altre informazioni, vedere Algoritmo di recapito. Lo stack host imposta 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 di NET_BUFFER_LIST indicate quando viene restituita la funzione NdisTcpOffloadReceiveHandler. Lo stack host imposta 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 sulla 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 RcvIndicationSize membro della struttura TCP_OFFLOAD_STATE_CACHED, lo stack host può specificare il numero ottimale di byte di dati che la destinazione offload deve fornire in una singola chiamata alla funzione NdisTcpOffloadReceiveHandler. Per altre informazioni, vedere uso delle dimensioni di indicazione di ricezione specificate.