LPFN_RIOSEND回呼函式 (mswsock.h)

發行項
03/09/2024

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

語法

LPFN_RIOSEND LpfnRiosend;

BOOL LpfnRiosend(
  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

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

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

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

RIO_MSG_DONT_NOTIFY

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

RIO_MSG_DEFER

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

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

注意

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

RequestContext

傳回值

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

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

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

備註

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

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

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

注意

在運行時間必須呼叫 WSAIoctl 函式，並指定SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode，以取得RIOSend 函式的函式指標。傳遞至 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 市集應用程式支援此函式。

規格需求

需求	值
標頭	mswsock.h