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

2025-02-07

La WskReceiveEvent función de devolución de llamada de eventos 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 WskAcceptEvent función de devolución de llamada de eventos 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, es posible que el subsistema WSK haya llamado a la función de devolución de llamada de evento 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 al WskCloseSocket función 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 el WskReceiveEvent función de devolución de llamada de evento devuelve un estado distinto de STATUS_SUCCESS, el subsistema WSK omite el valor de esta variable.

Valor devuelto

Una aplicación WSK WskReceiveEvent función de devolución de llamada de eventos 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 al WskReceiveEvent función de devolución de llamada de evento cuando se reciben nuevos datos en el socket. Sin embargo, si la aplicación WSK aceptaba solo una parte de los datos recibidos, el subsistema WSK no llamará a la función de devolución de llamada de evento WskReceiveEvent hasta que la aplicación WSK llame a la función WskReceive. Una vez que la aplicación WSK llama a la función de WskReceive, el subsistema WSK reanudará la llamada a la función de devolución de llamada de evento WskReceiveEvent con los datos almacenados en búfer restantes y cuando se reciben 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 WSK reanude la llamada al WskReceiveEvent función de devolución de llamada de eventos sin llamar a WskReceive 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 hayan recuperado 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 WSK_DATA_INDICATION estructuras al subsistema WSK. El subsistema WSK puede llamar al WskReceiveEvent función de devolución de llamada de eventos 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á a la función de devolución de llamada de evento WskReceiveEvent hasta que la aplicación WSK llame a la función WskReceive. Una vez que la aplicación WSK llama a la función de WskReceive, el subsistema WSK reanudará la llamada a la función de devolución de llamada de evento WskReceiveEvent con los datos almacenados en búfer restantes y cuando se reciben 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 WSK reanude la llamada al WskReceiveEvent función de devolución de llamada de eventos sin llamar a WskReceive recibir datos del socket.

Observaciones

El subsistema WSK llama a la WskReceiveEvent de una aplicación WSK función de devolución de llamada de eventos 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 previamente 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 WskReceiveEvent de una aplicación WSK función de devolución de llamada de eventos 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 evento WskReceiveEvent. El subsistema WSK llama a la WskReceiveEvent de la aplicación función de devolución de llamada de eventos 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 WskReceiveEvent función de devolución de llamada de eventos 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 WskReceiveEvent de la aplicación WskReceiveEvent función de devolución de llamada de eventos para el socket. La única manera de que una aplicación WSK asegúrese de que el subsistema WSK no llamará a la WskReceiveEvent función de devolución de llamada de eventos 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 WSK WskReceiveEvent de una aplicación WSK en IRQL <= DISPATCH_LEVEL.

Las WskReceiveEvent de una aplicación WSK función de devolución de llamada de eventos no deben esperar a que se completen otras solicitudes WSK en el contexto de las funciones de finalización de WSK o devolución de llamada de eventos. 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	Valor
cliente mínimo admitido	Disponible en Windows Vista y versiones posteriores de los sistemas operativos Windows.
de la plataforma de destino de	Windows
encabezado de	wsk.h (incluya Wsk.h)
irQL	<= DISPATCH_LEVEL