PFN_WSK_RECEIVE_EVENT función de devolución de llamada (wsk.h)

Artículo
08/08/2023

La función de devolución de llamada de eventos WskReceiveEvent notifica a una aplicación WSK que se han recibido datos en un socket orientado a la conexión.

Sintaxis

PFN_WSK_RECEIVE_EVENT PfnWskReceiveEvent;

NTSTATUS PfnWskReceiveEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATA_INDICATION DataIndication,
  [in]           SIZE_T BytesIndicated,
  [in, out]      SIZE_T *BytesAccepted
)
{...}

Parámetros

[in, optional] SocketContext

Puntero al contexto de socket para el socket orientado a la conexión que ha recibido los datos. La aplicación WSK proporcionó este puntero al subsistema WSK de una de las maneras siguientes:

Llamó a la función WskSocket para crear el socket.
Llamó a la función WskSocketConnect para crear el socket.
Llamó a la función WskAccept para aceptar el socket como una conexión entrante.
Se llamó a su función de devolución de llamada de eventos WskAcceptEvent para aceptar el socket como una conexión entrante.

[in] Flags

Valor de ULONG que contiene un OR bit a bit de una combinación de las marcas siguientes:

Valor	Significado
WSK_FLAG_RELEASE_ASAP	Si es posible, la aplicación WSK no debe conservar los búferes de datos que contienen los datos recibidos. Si la aplicación WSK conserva los búferes, debe liberarlos lo antes posible llamando a la función WskRelease .
WSK_FLAG_ENTIRE_MESSAGE	Los búferes de datos contienen un mensaje completo o la parte final de un mensaje. La interpretación de lo que constituye un mensaje completo es específico del protocolo de transporte. Para TCP, esta marca indica que el bit de inserción se estableció para uno o varios de los segmentos TCP que constituyen los datos de los búferes de datos.
WSK_FLAG_AT_DISPATCH_LEVEL	El subsistema WSK llamó a la función de devolución de llamada de eventos WskReceiveEvent en IRQL = DISPATCH_LEVEL. Si no se establece esta marca, el subsistema WSK podría haber llamado a la función de devolución de llamada de eventos WskReceiveEvent en cualquier irQL <= DISPATCH_LEVEL.

[in, optional] DataIndication

Puntero a una lista vinculada de estructuras de WSK_DATA_INDICATION que describen los datos recibidos. Si este parámetro es NULL, el socket ya no es funcional y la aplicación WSK debe llamar a la función WskCloseSocket para cerrar el socket lo antes posible.

[in] BytesIndicated

Número de bytes de datos recibidos descritos por la lista vinculada de estructuras de WSK_DATA_INDICATION .

[in, out] BytesAccepted

Puntero a una variable con tipo SIZE_T que recibe el número de bytes de datos recibidos aceptados por la aplicación WSK. Esta variable solo debe establecerse si la aplicación WSK acepta una parte del número total de bytes de datos recibidos. Si la aplicación WSK acepta todos los datos recibidos, no tiene que establecer esta variable. Si la función de devolución de llamada de eventos WskReceiveEvent devuelve un estado distinto de STATUS_SUCCESS, el subsistema WSK omite el valor de esta variable.

Valor devuelto

La función de devolución de llamada de eventos WSKReceiveEvent de una aplicación WSK puede devolver uno de los siguientes códigos NTSTATUS:

Código devuelto	Descripción
STATUS_SUCCESS	La aplicación WSK aceptó al menos algunos de los datos recibidos. Si la aplicación WSK aceptó todos los datos recibidos, el subsistema WSK puede llamar a la función de devolución de llamada de eventos WskReceiveEvent de nuevo cuando se reciben nuevos datos en el socket. Sin embargo, si la aplicación WSK solo acepta una parte de los datos recibidos, el subsistema WSK no llamará a la función de devolución de llamada de eventos WskReceiveEvent de nuevo hasta después de que la aplicación WSK llame a la función WskReceive . Una vez que la aplicación WSK llama a la función WskReceive , el subsistema WSK reanudará la llamada a la función de devolución de llamada de eventos WskReceiveEvent con los datos almacenados en búfer restantes y cuando se reciban nuevos datos en el socket. Una aplicación WSK puede llamar a la función WskReceive con un búfer de longitud cero, lo que hará que el subsistema de WSK reanude la llamada a la función de devolución de llamada de eventos WskReceive sin llamar a WskReceive para recibir datos del socket.
STATUS_PENDING	La aplicación WSK aceptó los datos, pero no recuperó todos los datos contenidos en la lista vinculada de estructuras de WSK_DATA_INDICATION . La aplicación WSK conserva la lista vinculada de WSK_DATA_INDICATION estructuras hasta que se recuperan todos los datos. Una vez que la aplicación WSK ha recuperado todos los datos, llama a la función WskRelease para liberar la lista vinculada de estructuras de WSK_DATA_INDICATION al subsistema WSK. El subsistema WSK puede llamar de nuevo a la función de devolución de llamada de eventos WskReceiveEvent cuando se reciben nuevos datos en el socket.
STATUS_DATA_NOT_ACCEPTED	La aplicación WSK no aceptó los datos. En esta situación, el subsistema WSK tendrá el búfer de transporte subyacente en el búfer de datos si es posible o si lo requiere el protocolo. El subsistema WSK no llamará de nuevo a la función de devolución de llamada de eventos WskReceiveEvent hasta después de que la aplicación WSK llame a la función WskReceive . Una vez que la aplicación WSK llama a la función WskReceive , el subsistema WSK reanudará la llamada a la función de devolución de llamada de eventos WskReceiveEvent con los datos almacenados en búfer restantes y cuando se reciban nuevos datos en el socket. Una aplicación WSK puede llamar a la función WskReceive con un búfer de longitud cero, lo que hará que el subsistema de WSK reanude la llamada a la función de devolución de llamada de eventos WskReceive sin llamar a WskReceive para recibir datos del socket.

Comentarios

El subsistema WSK llama a la función de devolución de llamada de eventos WSKReceiveEvent de una aplicación WSK cuando se reciben nuevos datos en un socket orientado a la conexión solo si la función de devolución de llamada de eventos se ha habilitado anteriormente con la opción de socket SO_WSK_EVENT_CALLBACK . Para obtener más información sobre cómo habilitar las funciones de devolución de llamada de eventos de un socket, consulte Habilitación y deshabilitación de funciones de devolución de llamada de eventos.

Si la función de devolución de llamada de eventos WskReceiveEvent de una aplicación WSK está habilitada en un socket orientado a la conexión y la aplicación también tiene una llamada pendiente a la función WskReceive en el mismo socket orientado a la conexión, después, cuando llegan los datos, la llamada pendiente a la función WskReceive tendrá prioridad sobre la función de devolución de llamada de eventos WskReceiveEvent . El subsistema WSK llama a la función de devolución de llamada de eventos WskReceiveEvent de la aplicación solo si no hay ningún IRP en cola de llamadas pendientes a la función WskReceive . Sin embargo, una aplicación WSK no debe suponer que el subsistema WSK no llamará a la función de devolución de llamada de eventos WskReceiveEvent de la aplicación para un socket orientado a la conexión que tenga una llamada pendiente a la función WskReceive . Existen condiciones de carrera en las que el subsistema WSK todavía podría llamar a la función de devolución de llamada de eventos WskReceiveEvent de la aplicación WSK para el socket. La única manera de que una aplicación WSK asegúrese de que el subsistema WSK no llamará a la función de devolución de llamada de eventos WskReceiveEvent de la aplicación para un socket orientado a la conexión es deshabilitar la función de devolución de llamada de eventos WskReceiveEvent de la aplicación en el socket.

Nota

Winsock Kernel (WSK) llama a esta devolución de llamada en serie, por lo que no siempre se invoca tan pronto como se reciben los datos.

El subsistema WSK llama a la función de devolución de llamada de eventos WSKReceiveEvent de una aplicación WSK en IRQL <= DISPATCH_LEVEL.

La función de devolución de llamada de eventos WSKReceiveEvent de una aplicación WSK no debe esperar a que se completen otras solicitudes de WSK en el contexto de las funciones de devolución de llamada de eventos o finalización de WSK. La devolución de llamada puede iniciar otras solicitudes de WSK (suponiendo que no pasa demasiado tiempo en DISPATCH_LEVEL), pero no debe esperar a su finalización incluso cuando se llama a la devolución de llamada en IRQL = PASSIVE_LEVEL.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows Vista y versiones posteriores de los sistemas operativos Windows.
Plataforma de destino	Windows
Encabezado	wsk.h (incluya Wsk.h)
IRQL	<= DISPATCH_LEVEL