LPFN_RIORECEIVEEX回呼函式 (mswsock.h)

發行項
03/05/2024

RIOReceiveEx 函式會在已連線的已註冊 I/O TCP 套接字或系結的已註冊 I/O UDP 套接字上接收網路數據，以及搭配 Winsock 已註冊 I/O 延伸模組使用的其他選項。

語法

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
)
{...}

參數

SocketQueue

描述項，識別連接的已註冊 I/O UDP 套接字或系結的已註冊 I/O UDP 套接字。

pData

要在其中接收數據之已註冊緩衝區部分的描述。

如果應用程式不需要在 UDP 數據報中接收數據承載，則系結的已註冊 I/O UDP 套接字此參數可能是 NULL。

DataBufferCount

數據緩衝區計數參數，指出數據是否要接收於 pData 參數所指向的緩衝區中。

如果 pData 為 NULL，這個參數應該設定為零。否則，此參數應該設定為 1。

pLocalAddress

完成時的緩衝區區段會保存接收網路數據的本機位址。

如果應用程式不想要接收本機位址，這個參數可能是 NULL 。如果此參數不是 NULL，則緩衝區區段至少必須是 SOCKADDR_INET 結構的大小。

pRemoteAddress

完成時的緩衝區區段會保存從中接收網路數據的遠端位址。

如果應用程式不想要接收遠端位址，這個參數可能是 NULL 。如果此參數不是 NULL，則緩衝區區段至少必須是 SOCKADDR_INET 結構的大小。

pControlContext

完成時的緩衝區配量會保存有關接收作業的其他控制資訊。

如果應用程式不想要接收其他控件資訊，這個參數可能是 NULL 。

pFlags

Flags

一組旗標，可修改 RIOReceiveEx 函 式的行為。

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 旗標，這會導致最後一個要求比其他要求更慢。

不同於 其他對RIOReceiveEx 函式的呼叫，當 RIO_MSG_COMMIT_ONLY 旗標設定為 對RIOReceiveEx 函式的呼叫不需要串行化時。針對單一RIO_RQ，可以在一個線程上呼叫RIO_MSG_COMMIT_ONLY來呼叫RIOReceiveEx 函式，同時在另一個線程上呼叫RIOReceiveEx 函式。

RIO_MSG_DONT_NOTIFY

當要求完成插入至其完成佇列時，要求不應該觸發 RIONotify 函式。

RIO_MSG_DEFER

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

在未設定RIO_MSG_DEFER旗標的情況下，在傳入 SocketQueue 參數的RIO_RQ上傳送接收要求之前，數據接收可能會延遲。若要觸發要求佇列中所有接收的執行，請在未設定RIO_MSG_DEFER旗標的情況下呼叫RIOReceive 或RIOReceiveEx 函式。

注意

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

RIO_MSG_WAITALL

在發生下列其中一個事件之前， 才能完成RIOReceiveEx 函 式：

pData 參數中呼叫端所提供的緩衝區配量已完全滿。
此連接已經關閉。
要求已取消或發生錯誤。

數據報套接字或訊息導向的無連接套接字不支援此旗標。

RequestContext

要與此接收作業相關聯的要求內容。

傳回值

如果沒有發生錯誤， 則RIOReceiveEx 函 式會傳回 TRUE。在此情況下，已成功起始接收作業，而且完成作業已排入佇列，或作業已成功起始，且稍後會排入佇列。

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

傳回碼	Description
WSAEFAULT	系統在嘗試在呼叫中使用指標自變數時偵測到無效的指標位址。如果在排入佇列或叫用作業之前傳入參數的任何 RIO_BUF 結構釋放緩衝區標識符，則會傳回此錯誤。
WSAEINVAL	無效的參數已傳遞至函式。如果 SocketQueue 參數無效， dwFlags 參數包含的值對接收作業無效，或已完成佇列的完整性遭到入侵，就會傳回此錯誤。您也可以針對參數的其他問題傳回此錯誤。
WSAENOBUFS	無法配置足夠的記憶體。如果與 SocketQueue 參數相關聯的 I/O 完成佇列已滿，或以零個接收專案建立 I/O 完成佇列，就會傳回此錯誤。
WSA_OPERATION_ABORTED	當接收作業擱置時，作業已經取消。如果在本機或遠端關閉套接字，或執行 WSAIoctl 中的SIO_FLUSH命令，則會傳回此錯誤。

備註

應用程式可以使用 RIOReceiveEx 函式，將網路數據完全包含在單一登錄緩衝區內的任何緩衝區中。 pData 參數所指向之RIO_BUF結構的 Offset 和 Length 成員會決定在緩衝區中接收網路數據的位置。

呼叫RIOReceiveEx函式之後，在 pData 參數中傳遞的緩衝區，包括RIO_BUF結構之 BufferId 成員中的RIO_BUFFERID，在接收作業期間必須維持有效狀態。

為了避免競爭狀況，與接收要求相關聯的緩衝區不應該在要求完成之前讀取或寫入。這包括使用緩衝區作為傳送要求的來源，或另一個接收要求的目的地。未與任何接收要求相關聯的已註冊緩衝區部分不會包含在這項限制中。

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

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

通訊協定	cmsg_level	cmsg_type	Description
IPv4	IPPROTO_IP	IP_ORIGINAL_ARRIVAL_IF	接收針對數據報套接字接收封包的原始 IPv4 抵達介面。當 Teredo、6to4 或 ISATAP 通道用於 IPv4 NAT 周遊時，防火牆會使用此控制數據。 cmsg_data[] 成員是ULONG，其中包含 ifdef.h 頭文件中定義的IF_INDEX。如需詳細資訊，請參閱 IP_ORIGINAL_ARRIVAL_IF 套接字選項的 IPPROTO_IP 套接字選項。
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 參數可用來影響RIOReceiveEx 函式調用的行為，超出為相關聯套接字指定的選項。此函式的行為是由與 SocketQueue 參數相關聯之套接字上設定的任何套接字選項和 Flags 參數中指定的值的組合所決定。

注意

必須在運行時間取得 RIOReceiveEx 函式的函式指標，方法是呼叫 WSAIoctl 函式 並指定SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode。傳遞至 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 市集應用程式支援此函式，Windows 8.1、Windows Server 2012 R2 及更新版本。

規格需求

需求	值
標頭	mswsock.h