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

  • Artículo

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

Sintaxis

LPFN_RIORECEIVEEX LpfnRioreceiveex;

int LpfnRioreceiveex(
                                                                                                                     RIO_RQ SocketQueue,
                                                                                                                     PRIO_BUF pData,
                                                                                                                     ULONG DataBufferCount,
                                                                                                                     PRIO_BUF pLocalAddress,
                                                                                                                     PRIO_BUF pRemoteAddress,
                                                                                                                     PRIO_BUF pControlContext,
                                                                                                                     PRIO_BUF pFlags,
                                                                                                                     DWORD Flags,
                                                                                                                     PVOID RequestContext
)
{...}

Parámetros

SocketQueue

Descriptor que identifica un socket UDP 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 una 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.

pLocalAddress

Un segmento de búfer que al finalizar contendrá la dirección local en la que se recibieron los datos de red.

Este parámetro puede ser NULL si la aplicación no quiere recibir la dirección local. Si este parámetro no es NULL, el segmento del búfer debe ser al menos el tamaño de una estructura de SOCKADDR_INET .

pRemoteAddress

Un segmento de búfer que al finalizar contendrá la dirección remota desde la que se recibieron los datos de red.

Este parámetro puede ser NULL si la aplicación no quiere recibir la dirección remota. Si este parámetro no es NULL, el segmento del búfer debe ser al menos el tamaño de una estructura de SOCKADDR_INET .

pControlContext

Un segmento de búfer que al finalizar contendrá información de control adicional sobre la operación de recepción.

Este parámetro puede ser NULL si la aplicación no desea recibir la información de control adicional.

pFlags

Flags

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

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 de RIO_MSG_COMMIT_ONLY , no se puede especificar ninguna otra marca. Cuando se establece la marca de RIO_MSG_COMMIT_ONLY , los argumentos pData, pLocalAddress, pRemoteAddress, pControlContext, pFlags y RequestContext deben ser NULL y el argumento DataBufferCount debe ser cero.

Normalmente, esta marca se usaría ocasionalmente después de emitir varias 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 RIOReceiveEx , cuando la marca de RIO_MSG_COMMIT_ONLY se establece en las llamadas a la función RIOReceiveEx no es necesario serializar. Para una sola RIO_RQ, se puede llamar a la función RIOReceiveEx con RIO_MSG_COMMIT_ONLY en un subproceso al llamar a la función RIOReceiveEx 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 todas las recepción en una cola de solicitudes, llame a la función RIOReceive o RIOReceiveEx sin la marca de 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 establece RIO_MSG_DEFER .

RIO_MSG_WAITALL

La función RIOReceiveEx 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 de datagramas ni en sockets sin conexión orientados a mensajes.

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 RIOReceiveEx 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 la operación se pone en cola o se invoque.
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 dwFlags 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 se ejecuta el comando SIO_FLUSH en WSAIoctl .

Comentarios

Una aplicación puede usar la función RIOReceiveEx 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 apuntados 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 RIOReceiveEx , 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 de una solicitud de envío o el destino de otra solicitud de recepción. Las partes de un búfer registrado que no están asociadas a ninguna solicitud de recepción no se incluyen en esta restricción.

El parámetro pLocalAddress se puede usar para recuperar la dirección local donde se recibieron los datos. El parámetro pRemoteAddress se puede usar para recuperar la dirección remota desde la que se recibieron los datos. Las direcciones locales y remotas se devuelven como estructuras de SOCKADDR_INET . Como resultado, el miembro Length del RIO_BUF apuntado por los parámetros pLocalAddress o pRemoteAddress debe ser igual o mayor que el tamaño de una estructura de SOCKADDR_INET .

En la tabla siguiente se resumen los distintos usos de datos de control disponibles para su uso con la información de control en el miembro pControlContext .

Protocolo cmsg_level cmsg_type Descripción
IPv4 IPPROTO_IP IP_ORIGINAL_ARRIVAL_IF Recibe la interfaz de llegada IPv4 original donde se recibió el paquete para los sockets de datagrama. Los firewalls usan estos datos de control cuando se usa un túnel Teredo, 6to4 o ISATAP para el recorrido NAT de IPv4.
El miembro cmsg_data[] es un ULONG que contiene el IF_INDEX definido en el archivo de encabezado ifdef.h .
Para obtener más información, consulte IPPROTO_IP Opciones de socket para la opción de socket IP_ORIGINAL_ARRIVAL_IF.
IPv4 IPPROTO_IP IP_PKTINFO Especifica o recibe información de paquetes.
Para obtener más información, consulte IPPROTO_IP Opciones de socket para la opción de socket IP_PKTINFO.
IPv6 IPPROTO_IPV6 IPV6_DSTOPTS Especifica o recibe opciones de destino.
IPv6 IPPROTO_IPV6 IPV6_HOPLIMIT Especifica o recibe el límite de saltos.
Para obtener más información, consulte IPPROTO_IPV6 Opciones de socket para la opción de socket IPV6_HOPLIMIT.
IPv6 IPPROTO_IPV6 IPV6_HOPOPTS Especifica o recibe opciones de salto a salto.
IPv6 IPPROTO_IPV6 IPV6_NEXTHOP Especifica la dirección del próximo salto.
IPv6 IPPROTO_IPV6 IPV6_PKTINFO Especifica o recibe información de paquetes.
Para obtener más información, consulte las opciones de socket IPPROTO_IPV6 para la opción de socket IPV6_PKTINFO.
IPv6 IPPROTO_IPV6 IPV6_RTHDR Especifica o recibe el encabezado de enrutamiento.

Los datos de control se componen de uno o varios objetos de datos de control, cada uno de los cuales comienza con una estructura WSACMSGHDR , definida como la siguiente:

} WSACMSGHDR;

Los miembros de la estructura WSACMSGHDR son los siguientes:

Término Descripción
cmsg_len Número de bytes de datos que comienzan desde el principio del WSACMSGHDR hasta el final de los datos (excepto los bytes de relleno que pueden seguir los datos).
cmsg_level Protocolo que originó la información de control.
cmsg_type Tipo específico del protocolo de información de control.

El parámetro Flags se puede usar para influir en el comportamiento de la invocación de función RIOReceiveEx 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 RIOReceiveEx debe obtenerse en tiempo de ejecución realizando una llamada a la función WSAIoctl con el código de operación SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER 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 devuela por la función WSAIoctl contiene un puntero a la estructura de 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