Expand Minimize

RIOReceiveEx function

The RIOReceiveEx function receives network data on a connected registered I/O TCP socket or a bound registered I/O UDP socket with additional options for use with the Winsock registered I/O extensions.

Syntax


BOOL  RIOReceiveEx(
  _In_  RIO_RQ SocketQueue,
  _In_  PRIO_BUF pData,
  _In_  ULONG DataBufferCount,
  _In_  PRIO_BUF pLocalAddress,
  _In_  PRIO_BUF pRemoteAddress,
  _In_  PRIO_BUF pControlContext,
  _In_  PRIO_BUF pFlags,
  _In_  DWORD Flags,
  _In_  PVOID RequestContext
);

Parameters

SocketQueue [in]

A descriptor that identifies a connected registered I/O UDP socket or a bound registered I/O UDP socket.

pData [in]

A description of the portion of the registered buffer in which to receive data.

This parameter may be NULL for a bound registered I/O UDP socket if the application does not need to receive a data payload in the UDP datagram.

DataBufferCount [in]

A data buffer count parameter that indicates if data is to be received in the buffer pointed to by the pData parameter.

This parameter should be set to zero if the pData is NULL. Otherwise, this parameter should be set to 1.

pLocalAddress [in]

A buffer segment that on completion will hold the local address on which the network data was received.

This parameter may be NULL if the application does not want to receive the local address. If this parameter is not NULL, then the buffer segment must be at least the size of a SOCKADDR_INET structure.

pRemoteAddress [in]

A buffer segment that on completion will hold the remote address from which the network data was received.

This parameter may be NULL if the application does not want to receive the remote address. If this parameter is not NULL, then the buffer segment must be at least the size of a SOCKADDR_INET structure.

pControlContext [in]

A buffer slice that on completion will hold additional control information about the receive operation.

This parameter may be NULL if the application does not want to receive the additional control information.

pFlags [in]

A buffer slice that on completion will hold additional information about the set of flags for the receive operation.

This parameter may be NULL if the application does not want to receive the additional flags information.

Flags [in]

A set of flags that modify the behavior of the RIOReceiveEx function.

The Flags parameter can contain a combination of the following options defined in the Mswsockdef.h header file:

FlagMeaning
RIO_MSG_COMMIT_ONLY

Previous requests added with RIO_MSG_DEFER flag will be committed.

When the RIO_MSG_COMMIT_ONLY flag is set, no other flags may be specified. When the RIO_MSG_COMMIT_ONLY flag is set, the pData, pLocalAddress, pRemoteAddress, pControlContext, pFlags, and RequestContext parameters must be NULL and the DataBufferCount parameter must be zero.

This flag would normally be used occasionally after a number of requests were issued with the RIO_MSG_DEFER flag set. This eliminates the need when using the RIO_MSG_DEFER flag to make the last request without the RIO_MSG_DEFER flag, which causes the last request to complete much slower than other requests.

Unlike other calls to the RIOReceiveEx function, when the RIO_MSG_COMMIT_ONLY flag is set calls to the RIOReceiveEx function do not need to be serialized. For a single RIO_RQ, the RIOReceiveEx function can be called with RIO_MSG_COMMIT_ONLY on one thread while calling the RIOReceiveEx function on another thread.

RIO_MSG_DONT_NOTIFY

The request should not trigger the RIONotify function when request completion is inserted into its completion queue.

RIO_MSG_DEFER

The request does not need to be executed immediately. This will insert the request into the request queue, but it may or may not trigger the execution of the request.

Data reception may be delayed until a receive request is made on the RIO_RQ passed in the SocketQueue parameter without the RIO_MSG_DEFER flag set. To trigger execution for all receives in a request queue, call the RIOReceive or RIOReceiveEx function without the RIO_MSG_DEFER flag set.

Note  The receive request is charged against the outstanding I/O capacity on the RIO_RQ passed in the SocketQueue parameter regardless of whether RIO_MSG_DEFER is set.

RIO_MSG_WAITALL

The RIOReceiveEx function will not complete until one of the following events occurs:

  • The buffer slice supplied by the caller in the pData parameter is completely full.
  • The connection has been closed.
  • The request has been canceled or an error occurred.

This flag is not supported on datagram sockets or on message-oriented connectionless sockets.

 

RequestContext [in]

The request context to associate with this receive operation.

Return value

If no error occurs, the RIOReceiveEx function returns TRUE. In this case, the receive operation is successfully initiated and the completion will have already been queued or the operation has been successfully initiated and the completion will be queued at a later time.

A value of FALSE indicates the function failed, the operation was not successfully initiated and no completion indication will be queued. A specific error code can be retrieved by calling the WSAGetLastError function.

Return codeDescription
WSAEFAULT

The system detected an invalid pointer address in attempting to use a pointer argument in a call. This error is returned if a buffer identifier is deregistered or a buffer is freed for any of the RIO_BUF structures passed in parameters before the operation is queued or invoked.

WSAEINVAL

An invalid parameter was passed to the function.

This error is returned if the SocketQueue parameter is not valid, the dwFlags parameter contains an value not valid for a receive operation, or the integrity of the completion queue has been compromised. This error can also be returned for other issues with parameters.

WSAENOBUFS

Sufficient memory could not be allocated. This error is returned if the I/O completion queue associated with the SocketQueue parameter is full or the I/O completion queue was created with zero receive entries.

WSA_OPERATION_ABORTED

The operation has been canceled while the receive operation was pending. This error is returned if the socket is closed locally or remotely, or the the SIO_FLUSH command in WSAIoctl is executed.

 

Remarks

An application can use the RIOReceiveEx function to receive network data into any buffer completely contained within a single registered buffer. The Offset and Length members of the RIO_BUF structure pointed to by the pData parameter determine where the network data is received in the buffer.

Once the RIOReceiveEx function is called, the buffer passed in the pData parameter including the RIO_BUFFERID in the BufferId member of RIO_BUF structure must remain valid for the duration of the receive operation.

In order to avoid race conditions, a buffer associated with a receive request should not be read or written before the request completes. This includes using the buffer as the source for a send request or the destination for another receive request. Portions of a registered buffer not associated with any receive request are not included in this restriction.

The pLocalAddress parameter can be used to retrieve the local address where the data was received. The pRemoteAddress parameter can be used to retrieve the remote address from which the data was received. The local and remote addresses are returned as SOCKADDR_INET structures. As a result, the Length member of the RIO_BUF pointed to by pLocalAddress or pRemoteAddress parameters should be equal or greater than the size of a SOCKADDR_INET structure.

The following table summarizes the various uses of control data available for use with the control information in the pControlContext member.

Protocolcmsg_levelcmsg_typeDescription
IPv4IPPROTO_IPIP_ORIGINAL_ARRIVAL_IF

Receives the original IPv4 arrival interface where the packet was received for datagram sockets. This control data is used by firewalls when a Teredo, 6to4, or ISATAP tunnel is used for IPv4 NAT traversal.

The cmsg_data[] member is a ULONG that contains the IF_INDEX defined in the ifdef.h header file.

For more information, see the IPPROTO_IP Socket Options for the IP_ORIGINAL_ARRIVAL_IF socket option.

IPv4IPPROTO_IPIP_PKTINFO

Specifies/receives packet information.

For more information, see the IPPROTO_IP Socket Options for the IP_PKTINFO socket option.

IPv6IPPROTO_IPV6IPV6_DSTOPTS

Specifies/receives destination options.

IPv6IPPROTO_IPV6IPV6_HOPLIMIT

Specifies/receives hop limit.

For more information, see the IPPROTO_IPV6 Socket Options for the IPV6_HOPLIMIT socket option.

IPv6IPPROTO_IPV6IPV6_HOPOPTS

Specifies/receives hop-by-hop options.

IPv6IPPROTO_IPV6IPV6_NEXTHOP

Specifies next-hop address.

IPv6IPPROTO_IPV6IPV6_PKTINFO

Specifies/receives packet information.

For more information, see the IPPROTO_IPV6 Socket Options for the IPV6_PKTINFO socket option.

IPv6IPPROTO_IPV6IPV6_RTHDR

Specifies/receives routing header.

 

Control data is made up of one or more control data objects, each beginning with a WSACMSGHDR structure, defined as the following:



struct wsacmsghdr {
  UINT        cmsg_len;
  INT         cmsg_level;
  INT         cmsg_type;
  /* followed by UCHAR cmsg_data[] */
} WSACMSGHDR;


The members of the WSACMSGHDR structure are as follows:

TermDescription

cmsg_len

The number of bytes of data starting from the beginning of the WSACMSGHDR to the end of data (excluding padding bytes that may follow data).

cmsg_level

The protocol that originated the control information.

cmsg_type

The protocol-specific type of control information.

 

The Flags parameter can be used to influence the behavior of the RIOReceiveEx function invocation beyond the options specified for the associated socket. The behavior of this function is determined by a combination of any socket options set on the socket associated with the SocketQueue parameter and the values specified in the Flags parameter.

Note  The function pointer to the RIOReceiveEx function must be obtained at run time by making a call to the WSAIoctl function with the SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode specified. The input buffer passed to the WSAIoctl function must contain WSAID_MULTIPLE_RIO, a globally unique identifier (GUID) whose value identifies the Winsock registered I/O extension functions. On success, the output returned by the WSAIoctl function contains a pointer to the RIO_EXTENSION_FUNCTION_TABLE structure that contains pointers to the Winsock registered I/O extension functions. The SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL is defined in the Ws2def.h header file. The WSAID_MULTIPLE_RIO GUID is defined in the Mswsock.h header file.

Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.

Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.

Requirements

Minimum supported client

Windows 8.1, Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Minimum supported phone

Windows Phone 8

Header

Mswsock.h

Library

Mswsock.lib

DLL

Mswsock.dll

See also

RIO_BUF
RIO_BUFFERID
RIO_EXTENSION_FUNCTION_TABLE
RIO_RQ
RIONotify
RIOReceive
SOCKADDR_INET
WSAIoctl
WSAMSG

 

 

Community Additions

ADD
Show:
© 2014 Microsoft