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

Artículo
08/08/2023

La función WskReceiveFrom recibe un datagrama y cualquier información de control asociada de una dirección de transporte remota.

Sintaxis

PFN_WSK_RECEIVE_FROM PfnWskReceiveFrom;

NTSTATUS PfnWskReceiveFrom(
  [in]            PWSK_SOCKET Socket,
  [in]            PWSK_BUF Buffer,
                  ULONG Flags,
  [out, optional] PSOCKADDR RemoteAddress,
  [in, out]       PULONG ControlLength,
  [out, optional] PCMSGHDR ControlInfo,
  [out, optional] PULONG ControlFlags,
  [in, out]       PIRP Irp
)
{...}

Parámetros

[in] Socket

Puntero a una estructura de WSK_SOCKET que especifica el objeto de socket para el socket de datagrama desde el que se va a recibir el datagrama.

[in] Buffer

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

Flags

Este parámetro está reservado para uso del sistema. Una aplicación WSK debe establecer este parámetro en cero.

[out, optional] RemoteAddress

Puntero a un búfer asignado por el autor de la llamada que recibe la dirección de transporte remota desde la que se originó el datagrama recibido. El búfer debe encontrarse en memoria no paginada. El búfer también debe ser lo suficientemente grande como para contener el tipo de estructura SOCKADDR específico que corresponde a la familia de direcciones que la aplicación WSK especificó al crear el socket de datagrama. Este puntero es opcional y puede ser NULL.

[in, out] ControlLength

Puntero a un ULONG que especifica el tamaño del búfer al que apunta el parámetro ControlInfo . Una vez completada la operación de recepción, la variable recibe el tamaño de la información de control asociada al datagrama recibido. Si el valor devuelto es cero, no hay ninguna información de control presente para el datagrama. Este puntero es opcional y puede ser NULL. Si este parámetro es NULL, se omite el parámetro ControlInfo .

[out, optional] ControlInfo

Puntero a un búfer asignado por el autor de la llamada que recibe la información de control asociada al datagrama recibido. Los datos de información de control asociados a un datagrama se componen de uno o varios objetos de datos de control, cada uno de los cuales comienza con una estructura CMSGHDR . Si no hay información de control presente para el datagrama recibido, el contenido del búfer no está definido. Este puntero es opcional y puede ser NULL. Si el parámetro ControlInfoLength es NULL, el parámetro ControlInfo debe ser NULL.

[out, optional] ControlFlags

Puntero a una variable con tipo ULONG que recibe el OR bit a bit de una combinación de las marcas siguientes:

MSG_BCAST

El datagrama se recibió como una difusión de capa de vínculo o con una dirección de transporte de destino que es una dirección de difusión.

MSG_MCAST

El datagrama se recibió con una dirección de transporte de destino que es una dirección de multidifusión.

MSG_TRUNC

El datagrama se truncaba porque el tamaño del datagrama era mayor que el tamaño del búfer especificado por el parámetro Buffer .

MSG_CTRUNC

Los datos de información de control se truncaron porque el número de bytes de información de control era mayor que el tamaño del búfer especificado por el parámetro ControlInfo .

Este parámetro es opcional y puede ser NULL.

[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

WskReceiveFrom devuelve uno de los siguientes códigos NTSTATUS:

Código devuelto	Descripción
STATUS_SUCCESS	Los datos se recibieron correctamente desde el 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 el datagrama del socket inmediatamente. El subsistema WSK completará el IRP después de haber recibido el datagrama 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.
Otros códigos de estado	Se produjo un error. El IRP se completará con el estado de error.

Comentarios

Si la aplicación WSK ha establecido una dirección de transporte remota fija para el socket de datagrama, el subsistema WSK descartará los datagramas recibidos de cualquier otra dirección de transporte remota. Para obtener más información sobre cómo establecer la dirección de transporte remota para un socket de datagrama, consulte SIO_WSK_SET_REMOTE_ADDRESS.

Si la función de devolución de llamada de eventos WskReceiveFromEvent de una aplicación WSK está habilitada en un socket de datagramas y la aplicación también tiene una llamada pendiente a la función WskReceiveFrom en el mismo socket de datagramas, cuando llegan los datagramas, la llamada pendiente a la función WskReceiveFrom tendrá prioridad sobre la función de devolución de llamada de eventos WskReceiveFromEvent . El subsistema WSK llama a la función de devolución de llamada de eventos WskReceiveFromEvent de la aplicación solo si no hay ningún IRP en cola de llamadas pendientes a la función WskReceiveFrom . 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 WskReceiveFromEvent de la aplicación para un socket de datagrama que tenga una llamada pendiente a la función WskReceiveFrom . 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 WskReceiveFromEvent 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 WskReceiveFromEvent de la aplicación en un socket de datagrama es deshabilitar la función de devolución de llamada de eventos WskReceiveFromEvent de la aplicación en el socket.

Si la función WskReceiveFrom 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. Además, la variable a la que apunta el parámetro ControlInfoLength , el búfer al que apunta el parámetro ControlInfo y la variable a la que apunta el parámetro ControlFlags también debe permanecer válida hasta que se complete el IRP. Si la aplicación WSK asignó estos búferes o variables con una de las funciones ExAllocateXxx , no puede liberar la memoria con la función ExFreeXxx correspondiente hasta que se complete el IRP. Si la aplicación WSK asignó estos búferes o variables en la pila, no puede devolver desde la función que llama a la función WskReceiveFrom 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