LPFN_RIOSENDEX回调函数 (mswsock.h)

项目
09/23/2023

RIOSendEx 函数在连接的已注册 I/O TCP 套接字或绑定的已注册 I/O UDP 套接字上发送网络数据，其中包含用于 Winsock 注册的 I/O 扩展的其他选项。

语法

LPFN_RIOSENDEX LpfnRiosendex;

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

参数

SocketQueue

标识连接的已注册 I/O TCP 套接字或绑定的已注册 I/O UDP 套接字的描述符。

pData

要从中发送数据的已注册缓冲区的缓冲区段。此参数指向 的 RIO_BUF 结构可以表示已注册缓冲区的一部分或完整的已注册缓冲区。

如果应用程序不需要在 UDP 数据报中发送数据有效负载，则对于绑定注册的 I/O UDP 套接字，此参数可能为 NULL。

DataBufferCount

一个数据缓冲区计数参数，指示是否在 pData 参数指向的缓冲区中发送数据。

如果 pData 为 NULL，则此参数应设置为零。否则，此参数应设置为 1。

pLocalAddress

此参数是保留的，必须为 NULL。

pRemoteAddress

来自注册缓冲区的缓冲区段，输入时该段保存网络数据要发送到的远程地址。

如果已连接套接字，此参数可能为 NULL 。

pControlContext

缓冲区切片在完成后将保存有关发送操作的其他控制信息。

如果应用程序不想接收其他控件信息，则此参数可能为 NULL 。

pFlags

一个缓冲区切片，完成后将保存有关发送操作的标志集的其他信息。

如果应用程序不希望接收其他标志信息，则此参数可能为 NULL 。

Flags

一组标志，用于修改 RIOSendEx 函数的行为。

Flags 参数可以包含以下选项的组合，这些选项在Mswsockdef.h头文件中定义：

RIO_MSG_COMMIT_ONLY

将提交以前使用 RIO_MSG_DEFER 标志添加的请求。

设置 RIO_MSG_COMMIT_ONLY 标志时，不能指定其他标志。设置RIO_MSG_COMMIT_ONLY标志后，pData、pLocalAddress、pRemoteAddress、pControlContext、pFlags 和 RequestContext 参数必须为 NULL，DataBufferCount 参数必须为零。

在设置了 RIO_MSG_DEFER 标志的情况下发出多个请求后，通常偶尔会使用此标志。这样就无需使用 RIO_MSG_DEFER 标志在没有 RIO_MSG_DEFER 标志的情况下发出最后一个请求，从而导致最后一个请求的完成速度比其他请求慢得多。

与对 RIOSendEx 函数的其他调用不同，设置 RIO_MSG_COMMIT_ONLY 标志时，不需要序列化对 RIOSendEx 函数的调用。对于单个RIO_RQ，可以在一个线程上使用RIO_MSG_COMMIT_ONLY调用 RIOSendEx 函数，同时在另一个线程上调用 RIOSendEx 函数。

RIO_MSG_DONT_NOTIFY

当请求完成插入到其完成队列时，请求不应触发 RIONotify 函数。

RIO_MSG_DEFER

不需要立即执行请求。这会将请求插入请求队列，但它可能会触发或不触发请求的执行。

发送数据可能会延迟，直到在未设置RIO_MSG_DEFER标志的情况下在 SocketQueue 参数中传递RIO_RQ发出发送请求。若要触发发送队列中所有发送的执行，请在不设置 RIO_MSG_DEFER 标志的情况下调用 RIOSend 或 RIOSendEx 函数。

注意

无论是否设置了RIO_MSG_DEFER，发送请求都会根据 SocketQueue 参数中传递的RIO_RQ上的未完成 I/O 容量收费。

RequestContext

要与此发送操作关联的请求上下文。

返回值

如果未发生错误， 则 RIOSendEx 函数返回 TRUE。在这种情况下，发送操作已成功启动，完成操作已排队或操作已成功启动，完成将在以后排队。

值为 FALSE 表示函数失败，操作未成功启动，并且不会将完成指示排入队列。可以通过调用 WSAGetLastError 函数来检索特定的错误代码。

返回代码	说明
WSAEFAULT	系统尝试在调用中使用指针参数时检测到指针地址无效。如果在将操作排队或调用之前，为参数中传递的任何 RIO_BUF 结构释放缓冲区标识符或释放缓冲区，则返回此错误。
WSAEINVAL	向该函数传递了无效参数。如果 SocketQueue 参数无效、 Flags 参数包含的值对发送操作无效，或者完成队列的完整性受到损害，则返回此错误。对于参数的其他问题，也可能会返回此错误。
WSAENOBUFS	无法分配足够的内存。如果与 SocketQueue 参数关联的 I/O 完成队列已满，或者 I/O 完成队列是使用零个发送条目创建的，则返回此错误。
WSA_IO_PENDING	操作已成功启动，稍后将排队完成。

注解

应用程序可以使用 RIOSendEx 函数从完全包含在单个已注册缓冲区中的任何缓冲区发送网络数据。 pData 参数指向的 RIO_BUF 结构的 Offset 和 Length 成员确定要从缓冲区发送的网络数据。

与发送操作关联的缓冲区不得与另一个发送或接收操作同时使用。缓冲区和缓冲区注册必须在发送操作期间保持有效。这意味着，当某个请求已挂起时，不应将相同的PRIO_BUF传递给 RIOSend (Ex) 请求。只有在完成正在进行的 RIOSend (Ex) 请求后，才应重复使用具有相同偏移量或不同偏移量和长度) 的相同PRIO_BUF (。此外，当发送数据引用注册的缓冲区 (部分或整个缓冲区) 时，不得使用整个已注册缓冲区，直到发送完成。这包括使用注册缓冲区的一部分进行接收操作或另一个发送操作。

pLocalAddress 参数可用于检索从中发送数据的本地地址。 pRemoteAddress 参数可用于检索数据发送到的远程地址。本地地址和远程地址作为 SOCKADDR_INET 结构返回。因此，pLocalAddress 或 pRemoteAddress 参数指向的RIO_BUF的 Length 成员应等于或大于SOCKADDR_INET结构的大小。

下表总结了可用于 pControlContext 成员中的控件信息的控件数据的各种用途。

协议	cmsg_level	cmsg_type	说明
IPv4	IPPROTO_IP	IP_PKTINFO	指定/接收数据包信息。有关详细信息，请参阅 IP_PKTINFO 套接字选项的 IPPROTO_IP 套接字选项。
IPv6	IPPROTO_IPV6	IPV6_DSTOPTS	指定/接收目标选项。
IPv6	IPPROTO_IPV6	IPV6_HOPLIMIT	指定/接收跃点限制。有关详细信息，请参阅 IPV6_HOPLIMIT 套接字选项的 IPPROTO_IPV6 套接字选项。
IPv6	IPPROTO_IPV6	IPV6_HOPOPTS	指定/接收逐个跃点选项。
IPv6	IPPROTO_IPV6	IPV6_NEXTHOP	指定下一跃点地址。
IPv6	IPPROTO_IPV6	IPV6_PKTINFO	指定/接收数据包信息。有关详细信息，请参阅 IPV6_PKTINFO 套接字选项的 IPPROTO_IPV6 套接字选项。
IPv6	IPPROTO_IPV6	IPV6_RTHDR	指定/接收路由标头。

控制数据由一个或多个控件数据对象组成，每个对象都以 WSACMSGHDR 结构开头，定义如下：

} WSACMSGHDR;

WSACMSGHDR 结构的成员如下所示：

术语	说明
cmsg_len	从 WSACMSGHDR 的开头到数据结尾的数据字节数 (不包括可能跟随数据) 的填充字节数。
cmsg_level	发起控件信息的协议。
cmsg_type	特定于协议的控件信息类型。

Flags 参数可用于影响为关联套接字指定的选项之外的 RIOSendEx 函数的行为。此函数的行为由与 SocketQueue 参数关联的套接字上设置的任何套接字选项和 Flags 参数中指定的值的组合决定。

注意

必须在运行时通过调用 WSAIoctl 函数并指定SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER操作码来获取指向 RIOSendEx 函数的函数指针。传递给 WSAIoctl 函数的输入缓冲区必须包含 WSAID_MULTIPLE_RIO，这是一个全局唯一标识符， (GUID) 其值标识 Winsock 注册的 I/O 扩展函数。成功后， WSAIoctl 函数返回的输出包含指向 RIO_EXTENSION_FUNCTION_TABLE 结构的指针，该结构包含指向 Winsock 注册的 I/O 扩展函数的指针。 SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL 在 Ws2def.h 头文件中定义。 WSAID_MULTIPLE_RIO GUID 在 Mswsock.h 头文件中定义。

Windows Phone 8：Windows Phone 8 及更高版本上的 Windows Phone 应用商店应用支持此函数。

Windows 8.1和Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更高版本的 Windows 应用商店应用支持此函数。

要求

要求	值
Header	mswsock.h

通过

LPFN_RIOSENDEX回调函数 (mswsock.h)

语法

参数

RIO_MSG_COMMIT_ONLY

RIO_MSG_DONT_NOTIFY

RIO_MSG_DEFER

返回值

注解

要求

反馈

其他资源