LPFN_RIORECEIVE回呼函式 (mswsock.h)

發行項
03/13/2024

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

語法

LPFN_RIORECEIVE LpfnRioreceive;

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

參數

SocketQueue

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

pData

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

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

DataBufferCount

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

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

Flags

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

Flags 參數可以包含標頭檔案中定義的Mswsockdef.h下列選項組合：

RIO_MSG_COMMIT_ONLY

將認可以 RIO_MSG_DEFER 旗標新增的先前要求。

設定 RIO_MSG_COMMIT_ONLY 旗標時，可能不會指定其他旗標。設定 RIO_MSG_COMMIT_ONLY 旗標時， pData 和 RequestContext 自變數必須是 NULL， 而且 DataBufferCount 自變數必須是零。

此旗標通常會在發出一些要求之後使用 RIO_MSG_DEFER 旗標集。這可在不使用 RIO_MSG_DEFER 旗標的情況下使用 RIO_MSG_DEFER 旗標來提出最後一個要求時，這會導致最後一個要求比其他要求更慢完成。

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

RIO_MSG_DONT_NOTIFY

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

RIO_MSG_DEFER

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

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

注意

不論是否已設定RIO_MSG_DEFER，接收要求都會針對在SocketQueue參數中傳遞的RIO_RQ未完成的 I/O 容量收費。

RIO_MSG_WAITALL

在發生下列其中一個事件之前， RIOReceive 函式將不會完成：

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

UDP 套接字不支援此旗標。

RequestContext

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

傳回值

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

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

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

備註

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

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

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

Flags 參數可用來影響RIOReceive 函式調用的行為，超出為相關聯套接字指定的選項。此函式的行為是由與 SocketQueue 參數相關聯之套接字上設定的任何套接字選項和 Flags 參數中指定的值的組合所決定。

注意

若要在運行時間取得 RIOReceive 函式的函式指標，您必須呼叫 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 Store 應用程式支援此函式。

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

規格需求

需求	值
標頭	mswsock.h

共用方式為