NDIS_TCP_OFFLOAD_RECEIVE_INDICATE função de retorno de chamada (ndischimney.h)

Artigo
08/07/2023

[O recurso de descarregamento de chaminé TCP foi preterido e não deve ser usado.]

Um destino de descarregamento chama a função NdisTcpOffloadReceiveHandler para indicar que os dados de rede recebidos estão disponíveis para consumo por um aplicativo cliente.

Sintaxe

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

Parâmetros

[in] NdisOffloadHandle

Um identificador que identifica a conexão TCP descarregada na qual a indicação está sendo feita. Quando a conexão foi descarregada, esse identificador foi fornecido no membro NdisOffloadHandle do NDIS_MINIPORT_OFFLOAD_BLOCK_LIST estrutura associada ao estado da conexão.

[in] NetBufferList

Um ponteiro para uma estrutura NET_BUFFER_LIST . Cada estrutura NET_BUFFER_LIST descreve uma lista de estruturas NET_BUFFER . Cada estrutura NET_BUFFER na lista é mapeada para uma cadeia de listas de descritores de memória (MDLs). Os MDLs contêm os dados recebidos. Os MDLs são bloqueados para que permaneçam residentes, mas não são mapeados para a memória do sistema.

A estrutura NET_BUFFER_LIST especificada por NetBufferList deve ser uma estrutura autônoma e não pode ser a primeira estrutura em uma lista vinculada de estruturas NET_BUFFER_LIST . Os destinos de descarregamento podem contornar essa limitação encadeando quantos MDLs forem necessários para o mesmo NET_BUFFER em uma indicação de recebimento de descarregamento.

[in] Status

O destino de descarregamento deve fornecer o seguinte valor de status:

NDIS_STATUS_SUCCESS

Isso indica que a pilha de host pode manter a propriedade das estruturas NET_BUFFER_LIST e das estruturas associadas até que ela retorne essas estruturas para o Função MiniportTcpOffloadReceiveReturn do destino de descarregamento.

[out] BytesConsumed

Um ponteiro para uma variável do tipo ULONG que recebe o número de bytes que foram consumidos pelo aplicativo cliente.

Retornar valor

A função NdisTcpOffloadReceiveHandler pode retornar um dos seguintes valores:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	O aplicativo cliente consumiu todos os dados de recebimento indicados.
NDIS_STATUS_OFFLOAD_DATA_NOT_ACCEPTED	O aplicativo cliente rejeitou todos os dados de recebimento indicados.
NDIS_STATUS_OFFLOAD_DATA_PARTIALLY_ACCEPTED	O aplicativo cliente consumiu um subconjunto dos dados de recebimento indicados. A quantidade de dados, em bytes, que foi consumida pelo aplicativo cliente é retornada na variável especificada pelo parâmetro BytesConsumed .

Comentários

Os buffers de recebimento são postados no Função MiniportTcpOffloadReceive do destino de descarregamento. Se as solicitações de recebimento prepostas (buffers fornecidos pelo aplicativo cliente) estiverem disponíveis para a conexão, o destino de descarregamento deverá transferir os dados de recebimento chamando o Função NdisTcpOffloadReceiveComplete . Para obter mais informações, consulte Algoritmo de entrega.

Todas as solicitações de recebimento devem ser concluídas pelo destino de descarregamento (mesmo que sejam solicitações de recebimento de zero byte).

Depois que um destino de descarregamento tiver indicado receber dados e que os dados foram recusados, o destino de descarregamento não poderá indicar esses dados novamente até que a pilha de host poste uma solicitação de recebimento:

Solicitações de recebimento normais
Se a pilha de host postar solicitações de recebimento normais, o destino de descarregamento deverá concluir essas solicitações antes de fazer qualquer indicação de recebimento. Para obter mais informações, consulte Algoritmo de entrega.
Solicitações de recebimento de bytes zero
A pilha de host pode postar uma solicitação de recebimento de bytes zero para habilitar as indicações de recebimento pelo destino de descarregamento. Uma solicitação de recebimento de bytes zero é aquela em que o valor do membro DataLength (para obter mais informações, consulte NET_BUFFER estrutura) é zero. Uma solicitação de recebimento de bytes zero não consome dados armazenados em buffer.

Durante a inicialização, o destino de descarregamento deve alocar dois pools de buffers, cada um contendo estruturas NET_BUFFER_LIST e estruturas NET_BUFFER. O destino de descarregamento usa um pool para fazer indicações de recebimento por meio da chaminé TCP ao chamar o Função NdisTcpOffloadReceiveHandler . O destino de descarregamento usa o outro pool para fazer indicações de recebimento por meio da interface NDIS de não carga ao chamar o Função NdisMIndicateReceiveNetBufferLists .

Cada estrutura de NET_BUFFER_LIST alocada deve ter apenas uma estrutura NET_BUFFER associada a ela. O número dessas estruturas a serem alocadas cabe ao gravador de driver. Para obter mais informações sobre como alocar essas estruturas, consulte Miniport Driver Buffer Management.

Desde que não esteja fazendo uma confirmação atrasada, o destino de descarregamento deve reconhecer os dados recebidos assim que o destino de descarregamento tiver buffers internos nos quais pode depositar os dados. O destino de descarregamento pode reconhecer os dados recebidos antes, durante ou depois de chamar a função NdisTcpOffloadReceiveHandler .

O destino de descarregamento sempre fornece um valor status de NDIS_STATUS_SUCCESS ao chamar a função NdisTcpOffloadReceiveHandler . Isso indica que a pilha de host pode manter a propriedade das estruturas NET_BUFFER_LIST e das estruturas associadas até que ela retorne essas estruturas para o destino de descarregamento.

Se a pilha de host retornar NDIS_STATUS_SUCCESS, indicando que o aplicativo cliente aceitou e consumiu os dados de recebimento, a pilha de host retornará as estruturas de NET_BUFFER_LIST para o Função MiniportTcpOffloadReceiveReturn do destino de descarregamento. A pilha de host definirá a variável especificada pelo parâmetro BytesConsumed como o número de bytes indicados pelo destino de descarregamento.
Se a pilha de host retornar NDIS_STATUS_NOT_ACCEPTED, indicando que o aplicativo cliente rejeitou os dados de recebimento, o destino de descarregamento retomará a propriedade das estruturas de NET_BUFFER_LIST indicadas no retorno da função NdisTcpOffloadReceiveHandler . O destino de descarregamento deve armazenar em buffer os dados de recebimento antecipando que o aplicativo cliente postará buffers de recebimento na conexão. Depois que as postagens do aplicativo cliente recebem buffers, o destino de descarregamento copia os dados de recebimento em buffer nos buffers postados e conclui os buffers postados chamando o Função NdisTcpOffloadReceiveComplete . Para obter mais informações, consulte Algoritmo de entrega. A pilha de host definirá a variável especificada pelo parâmetro BytesConsumed como zero.
Se a pilha de host retornar NDIS_STATUS_OFFLOAD_DATA_PARTIALLY_ACCEPTED, indicando que o aplicativo cliente consumiu um subconjunto dos dados de recebimento, o destino de descarregamento retomará a propriedade das estruturas de NET_BUFFER_LIST indicadas quando a função NdisTcpOffloadReceiveHandler retornar. A pilha de host definirá a variável especificada pelo parâmetro BytesConsumed como um valor diferente de zero que especifica a quantidade de dados, em bytes, que foi consumida pelo aplicativo cliente. O destino de descarregamento deve armazenar em buffer os dados de recebimento restantes, antecipando que o aplicativo cliente postará os buffers de recebimento na conexão.

Observe que o destino de descarregamento nunca fornece um valor status de NDIS_STATUS_RESOURCES ao chamar a função NdisTcpOffloadReceiveHandler .

No membro RcvIndicationSize da estrutura TCP_OFFLOAD_STATE_CACHED, a pilha de host pode especificar o número ideal de bytes de dados que o destino de descarregamento deve fornecer em uma única chamada para a função NdisTcpOffloadReceiveHandler . Para obter mais informações, consulte Usando o tamanho da indicação de recebimento especificado.