LPFN_RIOSENDEX回呼函式 (mswsock.h)

發行項
02/29/2024

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

不需要立即執行要求。這會將要求插入要求佇列中，但可能會或可能不會觸發要求的執行。

傳送數據可能會延遲，直到傳送要求在SocketQueue 參數中傳遞的 RIO_RQ上，而不會設定RIO_MSG_DEFER旗標。若要觸發傳送佇列中所有傳送的執行，請在未設定RIO_MSG_DEFER旗標的情況下呼叫RIOSend 或RIOSendEx 函式。

注意

不論是否已設定RIO_MSG_DEFER，傳送要求都會根據在SocketQueue 參數中傳遞RIO_RQ的未處理I/O容量收費。

RequestContext

要與此傳送作業相關聯的要求內容。

傳回值

如果未發生任何錯誤， 則RIOSendEx函 式會傳回 TRUE。在此情況下，已成功起始傳送作業，而且完成作業已排入佇列，或作業已成功起始，且稍後會排入佇列。

FALSE 值表示函式失敗、作業未成功起始，且不會排入佇列。呼叫 WSAGetLastError 函式，即可擷取特定的錯誤碼。

傳回碼	Description
WSAEFAULT	系統在嘗試在呼叫中使用指標自變數時偵測到無效的指標位址。如果在排入佇列或叫用作業之前傳入參數的任何 RIO_BUF 結構釋放緩衝區標識符，則會傳回此錯誤。
WSAEINVAL	無效的參數已傳遞至函式。如果 SocketQueue 參數無效， Flags 參數包含的值對傳送作業無效，或完成佇列的完整性已遭入侵，就會傳回此錯誤。您也可以針對參數的其他問題傳回此錯誤。
WSAENOBUFS	無法配置足夠的記憶體。如果與 SocketQueue 參數相關聯的 I/O 完成佇列已滿，或 I/O 完成佇列是以零傳送專案建立，就會傳回此錯誤。
WSA_IO_PENDING	作業已成功起始，且完成會在稍後排入佇列。

備註

應用程式可以使用 RIOSendEx 函式，從單一登錄緩衝區內完全包含的任何緩衝區傳送網路數據。 pData 參數所指向之RIO_BUF結構的 Offset 和 Length 成員會決定要從緩衝區傳送的網路數據。

與傳送作業相關聯的緩衝區不得與另一個傳送或接收作業同時使用。緩衝區和緩衝區註冊在傳送作業期間必須維持有效狀態。這表示當其中一個已擱置時，您不應該將相同的PRIO_BUF傳遞至 (Ex) 要求。只有在正式發行前小眾測試版的RIOSend (Ex) 要求完成之後，才應該使用相同位移或長度不同的位移和長度) 相同的PRIO_BUF (。此外，當傳送數據參考已註冊的緩衝區 (部分或整個緩衝區) 時，必須先完成傳送，才能使用整個已註冊的緩衝區。這包括針對接收作業或其他傳送作業使用已註冊緩衝區的一部分。

pLocalAddress 參數可用來擷取傳送數據的本機位址。 pRemoteAddress 參數可用來擷取傳送數據的遠端位址。本機和遠端位址會以 SOCKADDR_INET 結構傳回。因此，pLocalAddress 或 pRemoteAddress 參數所指向之RIO_BUF的 Length 成員應該等於或大於SOCKADDR_INET結構的大小。

下表摘要說明可用於 pControlContext 成員中控件資訊的各種控件數據用法。

通訊協定	cmsg_level	cmsg_type	Description
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 參數中指定的值的組合所決定。

注意

若要在運行時間取得RIOSendEx函式的函式指標，則必須透過使用指定的 SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode 呼叫 WSAIoctl 函式。傳遞至 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 Phone Store 應用程式支援此函式。

Windows 8.1 和 Windows Server 2012 R2：Windows 市集應用程式支援 Windows 8.1、Windows Server 2012 R2 及更新版本上的此函式。

規格需求

需求	值
標頭	mswsock.h