LPFN_RIORECEIVE función de devolución de llamada (mswsock.h)

La función RIOReceive recibe datos de red en un socket TCP de E/S registrado conectado o en un socket UDP de E/S registrado enlazado para su uso con las extensiones de E/S registradas de Winsock.

Sintaxis

LPFN_RIORECEIVE LpfnRioreceive;

BOOL LpfnRioreceive(
  RIO_RQ SocketQueue,
  PRIO_BUF pData,
  ULONG DataBufferCount,
  DWORD Flags,
  PVOID RequestContext
)
{...}

Parámetros

SocketQueue

Descriptor que identifica un socket TCP de E/S registrado conectado o un socket UDP de E/S registrado enlazado.

pData

Descripción de la parte del búfer registrado en el que se van a recibir datos.

Este parámetro puede ser NULL para un socket UDP de E/S registrado enlazado si la aplicación no necesita recibir la carga de datos en el datagrama UDP.

DataBufferCount

Parámetro de recuento de búferes de datos que indica si los datos se van a recibir en el búfer al que apunta el parámetro pData .

Este parámetro debe establecerse en cero si pData es NULL. De lo contrario, este parámetro debe establecerse en 1.

Flags

Conjunto de marcas que modifican el comportamiento de la función RIOReceive .

El parámetro Flags puede contener una combinación de las siguientes opciones, definidas en el archivo de Mswsockdef.h encabezado:

RIO_MSG_COMMIT_ONLY

Se confirmarán las solicitudes anteriores agregadas con RIO_MSG_DEFER marca.

Cuando se establece la marca RIO_MSG_COMMIT_ONLY , no se puede especificar ninguna otra marca. Cuando se establece la marca RIO_MSG_COMMIT_ONLY , los argumentos pData y RequestContext deben ser NULL y el argumento DataBufferCount debe ser cero.

Normalmente, esta marca se usaría ocasionalmente después de que se emitiera una serie de solicitudes con el conjunto de marcas RIO_MSG_DEFER . Esto elimina la necesidad de usar la marca RIO_MSG_DEFER para realizar la última solicitud sin la marca RIO_MSG_DEFER , lo que hace que la última solicitud se complete mucho más lentamente que otras solicitudes.

A diferencia de otras llamadas a la función RIOReceive , cuando la marca de RIO_MSG_COMMIT_ONLY se establece en las llamadas a la función RIOReceive no es necesario serializar. Para una sola RIO_RQ, se puede llamar a la función RIOReceive con RIO_MSG_COMMIT_ONLY en un subproceso al llamar a la función RIOReceive en otro subproceso.

RIO_MSG_DONT_NOTIFY

La solicitud no debe desencadenar la función RIONotify cuando se inserta la finalización de la solicitud en su cola de finalización.

RIO_MSG_DEFER

La solicitud no tiene que ejecutarse inmediatamente. Esto insertará la solicitud en la cola de solicitudes, pero puede desencadenar o no la ejecución de la solicitud.

La recepción de datos puede retrasarse hasta que se realice una solicitud de recepción en el RIO_RQ pasado en el parámetro SocketQueue sin la marca RIO_MSG_DEFER establecida. Para desencadenar la ejecución de todos los recibidos en una cola de solicitudes, llame a la función RIOReceive o RIOReceiveEx sin la marca RIO_MSG_DEFER establecida.

Nota

La solicitud de recepción se cobra por la capacidad de E/S pendiente en el RIO_RQ pasado en el parámetro SocketQueue , independientemente de si se ha establecido RIO_MSG_DEFER .

RIO_MSG_WAITALL

La función RIOReceive no se completará hasta que se produzca uno de los siguientes eventos:

• El segmento de búfer proporcionado por el autor de la llamada en el parámetro pData está completamente lleno.
• Se cerró la conexión.
• Se ha cancelado la solicitud o se ha producido un error.

Esta marca no se admite en sockets UDP.

RequestContext

Contexto de solicitud que se va a asociar a esta operación de recepción.

Valor devuelto

Si no se produce ningún error, la función RIOReceive devuelve TRUE. En este caso, la operación de recepción se inicia correctamente y la finalización ya se ha puesto en cola o la operación se ha iniciado correctamente y la finalización se pondrá en cola más adelante.

Un valor false indica que se produjo un error en la función, la operación no se inició correctamente y no se pondrá en cola ninguna indicación de finalización. Se puede recuperar un código de error específico llamando a la función WSAGetLastError .

Código devuelto	Descripción
WSAEFAULT	El sistema ha detectado una dirección de puntero no válida al intentar usar un argumento de puntero en una llamada. Este error se devuelve si se anula el registro de un identificador de búfer o se libera un búfer para cualquiera de las estructuras de RIO_BUF pasadas en parámetros antes de que se pone en cola o se invoca la operación.
WSAEINVAL	Se pasó un parámetro no válido a la función. Este error se devuelve si el parámetro SocketQueue no es válido, el parámetro Flags contiene un valor no válido para una operación de recepción o la integridad de la cola de finalización se ha puesto en peligro. Este error también se puede devolver para otros problemas con los parámetros.
WSAENOBUFS	No se pudo asignar memoria suficiente. Este error se devuelve si la cola de finalización de E/S asociada al parámetro SocketQueue está llena o la cola de finalización de E/S se creó con cero entradas de recepción.
WSA_OPERATION_ABORTED	La operación se ha cancelado mientras la operación de recepción estaba pendiente. Este error se devuelve si el socket se cierra local o remotamente, o el comando SIO_FLUSH en WSAIoctl se ejecuta en este socket.

Comentarios

Una aplicación puede usar la función RIOReceive para recibir datos de red en cualquier búfer completamente contenido en un único búfer registrado. Los miembros Offset y Length de la estructura de RIO_BUF señalados por el parámetro pData determinan dónde se reciben los datos de red en el búfer.

Una vez que se llama a la función RIOReceive , el búfer pasado en el parámetro pData , incluido el RIO_BUFFERID en el miembro BufferId de RIO_BUF estructura debe permanecer válido durante la operación de recepción.

Para evitar condiciones de carrera, un búfer asociado a una solicitud de recepción no debe leerse ni escribirse antes de que se complete la solicitud. Esto incluye el uso del búfer como origen para una solicitud de envío o el destino de otra solicitud de recepción. Las partes de un búfer registrado no asociado a ninguna solicitud de recepción no se incluyen en esta restricción.

El parámetro Flags se puede usar para influir en el comportamiento de la invocación de función RIOReceive más allá de las opciones especificadas para el socket asociado. El comportamiento de esta función viene determinado por una combinación de las opciones de socket establecidas en el socket asociado al parámetro SocketQueue y los valores especificados en el parámetro Flags .

Nota

El puntero de función a la función RIOReceive debe obtenerse en tiempo de ejecución realizando una llamada a la función WSAIoctl con el SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER código de operación especificado. El búfer de entrada pasado a la función WSAIoctl debe contener WSAID_MULTIPLE_RIO, un identificador único global (GUID) cuyo valor identifica las funciones de extensión de E/S registradas de Winsock. Si se ejecuta correctamente, la salida devuelta por la función WSAIoctl contiene un puntero a la estructura RIO_EXTENSION_FUNCTION_TABLE que contiene punteros a las funciones de extensión de E/S registradas de Winsock. El SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL se define en el archivo de encabezado Ws2def.h . El GUID de WSAID_MULTIPLE_RIO se define en el archivo de encabezado Mswsock.h .

Windows Phone 8: esta función es compatible con las aplicaciones de Windows Phone Store en Windows Phone 8 y versiones posteriores.

Windows 8.1 y Windows Server 2012 R2: esta función es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.

Requisitos

Requisito	Valor
Header	mswsock.h