LPFN_RIOSEND callback function (mswsock.h)

Article
09/21/2023

The RIOSend function sends network data on a connected registered I/O TCP socket or a bound registered I/O UDP socket for use with the Winsock registered I/O extensions.

Syntax

LPFN_RIOSEND LpfnRiosend;

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

Parameters

SocketQueue

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

pData

A description of the portion of the registered buffer from which to send data.

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

DataBufferCount

A data buffer count parameter that indicates if data is to be sent 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.

Flags

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

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

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 and RequestContext arguments must be NULL, and the DataBufferCount argument 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 more slowly than other requests.

Unlike other calls to the RIOSend function, when the RIO_MSG_COMMIT_ONLY flag is set, calls to the RIOSend function do not need to be serialized. For a single RIO_RQ, the RIOSend function can be called with RIO_MSG_COMMIT_ONLY on one thread while calling the RIOSend 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 doesn't 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.

Sending data might be delayed until a send request is made on the RIO_RQ passed in the SocketQueue parameter without the RIO_MSG_DEFER flag set. To trigger execution for all sends in a send queue, call the RIOSend or RIOSendEx function without the RIO_MSG_DEFER flag set.

Note

The send 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.

RequestContext

Return value

If no error occurs, the RIOSend function returns TRUE. In this case, the send 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 code	Description
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 Flags parameter contains a value not valid for a send 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 send entries.
WSA_IO_PENDING	The operation has been successfully initiated and the completion will be queued at a later time.

Remarks

An application can use the RIOSend function to send network data from 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 the network data to be sent from the buffer.

The buffer associated with a send operation must not be used concurrently with another send or receive operation. The buffer, and buffer registration, must remain valid for the duration of a send operation. This means that you should not pass the same PRIO_BUF to a RIOSend(Ex) request when one is already pending. Only after an in-flight RIOSend(Ex) request is complete should you re-use the same PRIO_BUF (either with the same offset or with a different offset and length). Furthermore, when send data references a registered buffer (either a portion or the entire buffer), the entire registered buffer must not be used until the send has completed. This includes using a portion of the registered buffer for a receive operation or another send operation.

The Flags parameter can be used to influence the behavior of the RIOSend function 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 RIOSend 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

Requirement	Value
Header	mswsock.h

Share via