NDIS_TCP_OFFLOAD_RECEIVE_INDICATE función de devolución de llamada (ndischimney.h)

Artículo
08/07/2023

[La característica de descarga de chimenea TCP está en desuso y no se debe usar.]

Un destino de descarga llama a la función NdisTcpOffloadReceiveHandler para indicar que los datos de red recibidos están disponibles para su consumo por parte de una aplicación cliente.

Sintaxis

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

Identificador que identifica la conexión TCP descargada en la que se realiza la indicación. Cuando se descargó la conexión, este identificador se proporcionó en el miembro NdisOffloadHandle del NDIS_MINIPORT_OFFLOAD_BLOCK_LIST estructura asociada al estado de conexión.

[in] NetBufferList

Puntero a una estructura NET_BUFFER_LIST . Cada estructura NET_BUFFER_LIST describe una lista de estructuras de NET_BUFFER . Cada estructura NET_BUFFER de la lista se asigna a una cadena de listas de descriptores de memoria (MDL). Las MDL contienen los datos recibidos. Las MDL están bloqueadas para que permanezcan residentes, pero no se asignan a la memoria del sistema.

La estructura NET_BUFFER_LIST especificada por NetBufferList debe ser una estructura independiente y no puede ser la primera estructura de una lista vinculada de NET_BUFFER_LIST estructuras. Los destinos de descarga pueden solucionar esta limitación mediante el encadenamiento de tantas MDL como sea necesario a la misma NET_BUFFER en una indicación de recepción de descarga.

[in] Status

El destino de descarga debe proporcionar el siguiente valor de estado:

NDIS_STATUS_SUCCESS

Esto indica que la pila de hosts puede conservar la propiedad de las estructuras NET_BUFFER_LIST y las estructuras asociadas hasta que devuelve estas estructuras a la MiniportTcpOffloadReceiveReturn función del destino de descarga.

[out] BytesConsumed

Puntero a una variable con tipo ULONG que recibe el número de bytes consumidos por la aplicación cliente.

Valor devuelto

La función NdisTcpOffloadReceiveHandler puede devolver uno de los siguientes valores:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	La aplicación cliente consumió todos los datos de recepción indicados.
NDIS_STATUS_OFFLOAD_DATA_NOT_ACCEPTED	La aplicación cliente rechazó todos los datos de recepción indicados.
NDIS_STATUS_OFFLOAD_DATA_PARTIALLY_ACCEPTED	La aplicación cliente consumió un subconjunto de los datos de recepción indicados. La cantidad de datos, en bytes, que consumió la aplicación cliente se devuelve en la variable especificada por el parámetro BytesConsumed .

Comentarios

Los búferes de recepción se publican en Función MiniportTcpOffloadReceive del destino de descarga. Si las solicitudes de recepción prepostadas (búferes proporcionados por la aplicación cliente) están disponibles para la conexión, el destino de descarga debe transferir los datos de recepción mediante una llamada a . Función NdisTcpOffloadReceiveComplete . Para obtener más información, consulte Algoritmo de entrega.

El destino de descarga debe completar todas las solicitudes de recepción (incluso si son solicitudes de recepción de cero bytes).

Una vez que un destino de descarga ha indicado los datos de recepción y que se han rechazado, el destino de descarga no puede indicar de nuevo los datos hasta que la pila de hosts publique una solicitud de recepción:

Solicitudes de recepción normales
Si la pila de hosts publica solicitudes de recepción normales, el destino de descarga debe completar estas solicitudes antes de realizar cualquier indicación de recepción. Para obtener más información, consulte Algoritmo de entrega.
Solicitudes de recepción de bytes cero
La pila de hosts puede publicar una solicitud de recepción de cero bytes para habilitar las indicaciones de recepción por parte del destino de descarga. Una solicitud de recepción de cero bytes es una en la que el valor del miembro DataLength (para obtener más información, vea NET_BUFFER estructura) es cero. Una solicitud de recepción de cero bytes no consume ningún dato almacenado en búfer.

Durante la inicialización, el destino de descarga debe asignar dos grupos de búferes, cada uno de los cuales contiene NET_BUFFER_LIST estructuras y estructuras NET_BUFFER. El destino de descarga usa un grupo para realizar indicaciones de recepción a través de la chimenea TCP al llamar al Función NdisTcpOffloadReceiveHandler . El destino de descarga usa el otro grupo para realizar indicaciones de recepción a través de la interfaz NDIS sin descarga al llamar al Función NdisMIndicateReceiveNetBufferLists .

Cada estructura de NET_BUFFER_LIST asignada debe tener solo una estructura NET_BUFFER asociada. El número de estas estructuras que se van a asignar es hasta el escritor de controladores. Para obtener más información sobre cómo asignar estas estructuras, vea Miniport Driver Buffer Management.

Siempre que no realice una confirmación diferida, el destino de descarga debe confirmar los datos recibidos tan pronto como el destino de descarga tenga búferes internos en los que pueda depositar los datos. El destino de descarga puede confirmar los datos recibidos antes, durante o después de llamar a la función NdisTcpOffloadReceiveHandler .

El destino de descarga siempre proporciona un valor status de NDIS_STATUS_SUCCESS al llamar a la función NdisTcpOffloadReceiveHandler . Esto indica que la pila de hosts puede conservar la propiedad de las estructuras de NET_BUFFER_LIST y las estructuras asociadas hasta que devuelve estas estructuras al destino de descarga.

Si la pila de hosts devuelve NDIS_STATUS_SUCCESS, lo que indica que la aplicación cliente aceptó y consumió los datos de recepción, la pila de hosts devolverá las estructuras NET_BUFFER_LIST a la MiniportTcpOffloadReceiveReturn función del destino de descarga. La pila de hosts establecerá la variable especificada por el parámetro BytesConsumed en el número de bytes indicados por el destino de descarga.
Si la pila de hosts devuelve NDIS_STATUS_NOT_ACCEPTED, lo que indica que la aplicación cliente rechazó los datos de recepción, el destino de descarga reanuda la propiedad de las estructuras NET_BUFFER_LIST indicadas al devolver la función NdisTcpOffloadReceiveHandler . El destino de descarga debe almacenar en búfer los datos de recepción en previsión de que la aplicación cliente publicará los búferes de recepción en la conexión. Una vez que la aplicación cliente publica los búferes de recepción, el destino de descarga copia los datos de recepción almacenados en búferes publicados y completa los búferes publicados mediante una llamada a . Función NdisTcpOffloadReceiveComplete . Para obtener más información, consulte Algoritmo de entrega. La pila de hosts establecerá la variable especificada por el parámetro BytesConsumed en cero.
Si la pila de hosts devuelve NDIS_STATUS_OFFLOAD_DATA_PARTIALLY_ACCEPTED, lo que indica que la aplicación cliente consumió un subconjunto de los datos de recepción, el destino de descarga reanuda la propiedad de las estructuras de NET_BUFFER_LIST indicadas cuando se devuelve la función NdisTcpOffloadReceiveHandler . La pila de hosts establecerá la variable especificada por el parámetro BytesConsumed en un valor distinto de cero que especifica la cantidad de datos, en bytes, que la aplicación cliente consumió. El destino de descarga debe almacenar en búfer los datos de recepción restantes en previsión de que la aplicación cliente publicará los búferes de recepción en la conexión.

Tenga en cuenta que el destino de descarga nunca proporciona un valor status de NDIS_STATUS_RESOURCES al llamar a la función NdisTcpOffloadReceiveHandler .

En el miembro RcvIndicationSize de la estructura de TCP_OFFLOAD_STATE_CACHED, la pila de hosts puede especificar el número óptimo de bytes de datos que el destino de descarga debe proporcionar en una sola llamada a la función NdisTcpOffloadReceiveHandler . Para obtener más información, vea Usar el tamaño de indicación de recepción especificado.