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

Artículo
08/08/2023

La función WskReceive recibe datos a través de un socket orientado a la conexión o de flujo desde una dirección de transporte remota.

Sintaxis

PFN_WSK_RECEIVE PfnWskReceive;

NTSTATUS PfnWskReceive(
  [in]      PWSK_SOCKET Socket,
  [in]      PWSK_BUF Buffer,
  [in]      ULONG Flags,
  [in, out] PIRP Irp
)
{...}

Parámetros

[in] Socket

Puntero a una estructura WSK_SOCKET que especifica el objeto de socket para el socket desde el que se van a recibir los datos.

[in] Buffer

Puntero a una estructura de WSK_BUF inicializada que describe el búfer de datos que recibe los datos del socket.

[in] Flags

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

WSK_FLAG_WAITALL

Espere hasta que se rellene completamente el búfer de datos. Si se especifica esta marca, el IRP especificado en el parámetro Irp no se completará hasta que se produzca uno de los siguientes eventos:

El búfer de datos descrito por la estructura WSK_BUF a la que apunta el parámetro Buffer se rellena por completo.
El remitente remoto desconecta correctamente la conexión.
La conexión está desconectada de forma anulada por la aplicación WSK o por el remitente remoto.
Se cancela el IRP especificado.

Esta marca es compatible con el protocolo de transporte TCP/IP de Microsoft. Es posible que esta marca no sea compatible con otros protocolos de transporte.

WSK_FLAG_DRAIN

Espere hasta que se desconecte el socket y descarte los datos que se reciben en el socket. Si se especifica esta marca, el IRP especificado no se completará hasta que se produzca uno de los siguientes eventos:

El remitente remoto desconecta correctamente la conexión.
La conexión está desconectada de forma anulada por la aplicación WSK o por el remitente remoto.
Se cancela el IRP especificado.

El subsistema WSK descarta los datos recibidos. No se copiarán datos recibidos en el búfer de datos. El parámetro Buffer sigue siendo necesario cuando se especifica esta marca, pero la longitud del búfer que describe la estructura WSK_BUF debe ser cero.

Esta marca es compatible con el protocolo de transporte TCP/IP de Microsoft. Es posible que esta marca no sea compatible con otros protocolos de transporte.

Las marcas WSK_FLAG_WAITALL y WSK_FLAG_DRAIN son mutuamente excluyentes. Una aplicación WSK no debe especificar ambas marcas al mismo tiempo.

[in, out] Irp

Puntero a un IRP asignado por el autor de la llamada que usa el subsistema WSK para completar la operación de recepción de forma asincrónica. Para obtener más información sobre el uso de IRP con funciones WSK, consulte Uso de IRP con funciones del kernel de Winsock.

Valor devuelto

WskReceive devuelve uno de los siguientes códigos NTSTATUS:

Código devuelto	Descripción
STATUS_SUCCESS	Los datos se recibieron correctamente del socket. El IRP se completará con el estado correcto. El campo IoStatus.Information del IRP contiene el número de bytes recibidos.
STATUS_PENDING	El subsistema WSK no pudo recibir los datos del socket inmediatamente. El subsistema WSK completará el IRP después de haber recibido los datos del socket. El estado de la operación de recepción se devolverá en el campo IoStatus.Status del IRP. Si la operación se realiza correctamente, el campo IoStatus.Information del IRP contendrá el número de bytes recibidos.
STATUS_FILE_FORCED_CLOSED	El socket ya no es funcional. El IRP se completará con el estado de error. La aplicación WSK debe llamar a la función WskCloseSocket para cerrar el socket lo antes posible.
STATUS_NOT_SUPPORTED	El transporte de red subyacente no admite una marca especificada.
Otros códigos de estado	Se produjo un error. El IRP se completará con el estado de error.

Comentarios

Una aplicación WSK puede llamar a la función WskReceive solo en un socket de flujo o orientado a la conexión que se ha conectado previamente a una dirección de transporte remota. Un socket orientado a la conexión se conecta a una dirección de transporte remota mediante uno de los métodos siguientes:

La aplicación WSK conecta el socket mediante una llamada a la función WskConnect .
La aplicación WSK crea, enlaza y conecta el socket mediante una llamada a la función WskSocketConnect .
El subsistema WSK conecta el socket cuando la aplicación WSK acepta una solicitud de conexión entrante en un socket de escucha.

Si la función de devolución de llamada de eventos WSK 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, entonces, 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.

Una aplicación WSK puede llamar a la función WskReceive con una longitud cero especificada en el miembro Length de la estructura WSK_BUF a la que apunta el parámetro Buffer . Especificar una longitud cero en este miembro es útil en las situaciones siguientes:

Al volver a habilitar la función de devolución de llamada de eventos WskReceiveEvent para un socket después de que la función de devolución de llamada del evento WskReceiveEvent devolvió previamente STATUS_DATA_NOT_ACCEPTED
Al especificar la marca WSK_FLAG_DRAIN para descartar los datos adicionales que se reciben en el socket

Si la función WskReceive devuelve STATUS_PENDING, la cadena MDL que se describe en la estructura WSK_BUF a la que apunta el parámetro Buffer debe permanecer bloqueada en memoria hasta que se complete el IRP.

Requisitos

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